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Summary of Changes 



December 1988 Edition 



The following summarizes the changes made to the former (February 1987) edi- 
tion of this manual that appear in this edition: 

New Compiler Options. The -cord and -feedback driver options were 
added to the summary of driver options in the table on p. 1-8. The Reduc- 
ing Cache Conflicts section in Chapter 4 has been added to show how use 
of these options can create significant improvements in program perform- 
ance. 

New Link Editor Options: The -jmopt, and -nojmpopt link editor op- 
tions are described in Table 1.1 in Chapter 1. The Filling Jump Delay 
Slots section in Chapter 4 describes when to use these options. 

Pascal: the text in Chapter 2 (pp. 2-9 - 2-9) concerning the mapping of 
Pascal objects has been greatly expanded with additional rules and exam- 
ples. Additional information has also been provided in Chapter 3 (p. 3-2) 
on the interface between programs written in Pascal and those written in C. 

Index. Approximately 200 entries have been added to the Index, enhancing 
the ability to retrieve information from this manual more efficiently. 

General. Numerous minor technical and editorial corrections have been 
made throughout the manual. 
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About This Book 



Scope 



Audience 



This book provides information on the compilers and high-level languages that 
comprise the MIPS RISCompiler System. 

The RISCompiler system provides a consistent programming environment for 
all currently supported languages. This book describes the components and pro- 
gramming tools that comprise the compiler system. 



Although the programming environment includes all standard UNIX driver 
commands and system tools, this book does not describe those tools in detail. 
For details, you may need to refer to the User's Reference Manual and other 
associated publications. This book contains implementation details on the sup- 
ported languages, but does not contain detailed reference information giving the 
syntax and definition of each language. 



This book assumes that you are fluent in the programming language you're us- 
ing and that you are comfortable using the tools of the UNIX system (System V 
or BSD) to write your programs. It also assumes that you are using a MIPS 
RISComputer to compile your programs. 

If you need to compile, to debug, to profile, or to optimize, code, you need to 



read this book. 

Topics Covered 

This book has these chapters 



Chapter 1: The Compiler System. Gives an overview of components of the 
compiler system and provides reference and guide information in using the vari- 
ous options provided by the compiler drivers. 

Chapter 2: Storage Mapping. Describes storage mapping for variables in C 
and Pascal. 

Chapter 3: Language Interfaces. Provides reference and guide information 
in writing programs in C and Pascal that can communicate with each other. 

Chapter 4: Improving Program Performance. Describes the profiling and 
optimization facilities available to increase the efficiency of your programs, and 
how to use them. 

Chapter 5: Debugging Your Code. Shows you how to use the features of the 
source level debugger. 

Appendix A: C Implementation. Describes extensions and modifications 
supported by the C compiler that differ from other C implementations. 
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Appendix B: Pascal Implementation. Describes language extensions and 
modifications supported by the Pascal compiler that differ from other Pascal | 

implementations. ^ 

Appendix C: Byte Ordering. Describes how the big endian and Mtfle endian 
affect the mapping of data in storage. 

Index. Contains index entries for this publication. 

Publications Index. Contains index entries to other MIPS publications. 

For More Information 

You may need to refer to the following as you use this manual: 

MIPS Assembly Language Programmer's Guide 3201DOC 
RISC/os User's Reference Manual 3204DOC 

ar(l) 

dbx(l) 

prof(l) 

cc(l) 

f77(l) f 

pc(D 

W(l) 

dump(l) 

ffle(l) 

nm(l) 
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Overview 



The Drivers 



1 

The Compiler System 



Chapter 1 describes the components of the compiler system and how to use 
them. 



The components that comprise the compiler system and the task each performs 
are summarized in the following figure: 



Task 



Tool 




Intelligent programs called drivers actually invoke the following major compo- 
nents of the compiler system: the macro preprocessor (cpp), the compilers (C, 
FORTRAN 77, COBOL, PL/I or Pascal), the assembler, and the link editor. A 
separate driver exists for each language. This section gives an overview of 
driver operations and commands. 
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Languages Supported 



The table below shows the languages supported by the compiler system and the 
driver name that invokes the respective drivers: 



c 



Language 


Driver Name 


Operands 


C 


cc 


[compiler options] 
[link editor options] 
[source name list] 


Pascal 


pc 


[compiler options] 
[link editor options] 
[source name list] 


FORTRAN 77 


f77 


[compiler options] 
[link editor options] 
[source name list] 


COBOL 


cobol 


[compiler options] 
[link editor options] 
[source name list] 


PL/I 


pll 


[compiler options] 
[link editor options] 
[source name list] 


MIPS Assembly 


as 


[compiler options] 
[source name list] 



( 



Driver Commands 



NOTE: The languages supported by any one system is an optional choice 
made at purchase. Thus, the configuration of your particular system may not 
support all of the above languages. 

The commands cc(l), pc(l) ? cobol(l), pll(l) and f77(l), and as(l) run the driv- 
ers that cause your programs to be compiled (if in a high-level language), opti- 
mized, assembled, and link edited. 



( 
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Each command knows the appropriate libraries associated with the main pro- 
gram and passes only those libraries to the link editor. 



Files 



The driver recognizes the contents of an input file by the suffix assigned to the 
filename, as shown below. 



File Suffixes 


Suffix 


Description 


•P 


Pascal source code 


.u 
.a 
.b 
.c 
.cob 


ucode object file 
object library 
ucode object library 
C source code 
COBOL source code 


.e 


efl source 


.f 


Fortran 77 source 


.i 


The driver assumes that the source code 
was processed by the C preprocessor 
(cpp ) and that source code is that of 
of the processing driver. For example: 




pc -c source. i 




source.i is assumed to contain Pascal 
source statements. 


.0 


object file 


pll or 
pli 


PL/1 source code 


.r 


ratfor source code 


♦S 


assembly source code 



NOTE: The assembly driver as assumes that any file, regardless of the suffix, 
contains assembly language statements; as accepts only one input source file. 



Operational Overview 



Figure 1.1 on the next page show the relationship between the major compo- 
nents of the compiler system and their primary inputs and outputs, 

Note that FORTRAN uses preprocessors (see Figure 1,2) that the other lan- 
guages do not use. For more information, see the efl(l), ratfor(l), and m4(l) 
manual pages in the User's Reference Manual. 
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FORTRAN 
Preprocessors 



Macro 
Preprocessor 
(cpp) 




Assembler 




Front Ends 

(C, Pascal, Fortran 
Cobol, PL/1 



Procedure Merge 
(umerge) 



-02 




Global Optimizer 
(uopt) 



-01 



Code Generator 
(ugen) 



.S 


2E5S£SS$3£5 


•p 




KMRM 


wi^^s 


.c 


.f 



.cob 



.pir 



'or 



.pli 



Source files. 



Ucode library. 



7Z88BZZ&3 



^^^ 




Assembler file. 



1 Assembled 
object file. 



^^^ 



a.out 



Linked 
Object file. 



Figure 1.1. The Compiler System Driver. 
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-cpp driver option 




FORTRAN 
Front End 



Default Options 



Figure 1.2 The FORTRAN Preprocessors. See Figure 1.1. 

At compilation, you can select one or more options that affect a variety of pro- 
gram development functions, including debugging, optimization, and profiling 
facilities, and the names assigned to output files. 

Some options have defaults, which apply even if you don't specify them. For 
example, the default names for output files are filename. o for object files, where 
filename is the base name of the source file; the default name for executable 
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program objects is a.out. The following example uses the defaults in compiling 
source files foo.c and bar.c: 



% cc f oo . c. bar . c 



runs the C compiler, creates object 
modules foo.o and bar.o, and the 
executable program a.out. 



c 



Compiling Multi-Language Programs 



When the source language of the main program differs from that of a subpro- 
gram, you should compile each program module separately with the appropriate 
driver and then link them in a separate step. You can create objects suitable for 
link editing by specifying the -c option, which stops the driver immediately af- 
ter the assembler phase. For example: 

% cc ~c main.c more.c 
% pc -c rest.p 

The figure below shows the compilation control flow for these two commands. 
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Linking Objects 



You can also use a driver command to link edit separate objects into one exe- 
cutable program, The driver recognizes the .0 suffix as the name of a file con- 
taining object code suitable for link editing and immediately invokes the link 
editor. You could link edit the object created in the last example using Pascal 
driver pc, as shown below: 

% pc -o all main .0 more .0 rest .0 
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This statement produces the executable program object all. You could achieve 
the same results using the C driver cc, as shown below: 

% cc -o all main . o more . o rest . o -Ip -1m 

The cc driver needs two additional options, which pc uses by default and which 
are specified using the link editor -1 option: -Ip (which specifies the Pascal link 
library) and -Im (which specifies the math link library). Both pc and cc use the 
C link library by default. 

The figure below shows the flow of control for both the pc and cc commands 
listed above. 



mmm 




mmm 




mmm 









main.o more.o rest.o 



Link Editor 



T 



all 




Link Libraries 



For more information on the link editor and on specifying link libraries, see the 
Link Editor section of this chapter. For a detailed listing of the default librar- 
ies used by each driver, see the cc(l), f77(l), pc(l), cobol(l), or pll(l) manual 
page, as applicable, in the User's Reference Manual. 



Compilation Options 



The tables on the following pages summarize the options you can specify for 
the compilation phases, which include the preprocessing phase through the as- 
sembly phase (Figure 1.1 shows these phases); the options summaries are di- 
vided into the following major groups: 

• General Options 

• Byte Ordering Options 

• Debugging Options 

• Profiling Option 

• Optimizer Options 

• Compiler Development Options 
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General Options 



NOTE: The tables list only the most frequently used options; they don't list all 
available options. See the cc(l), f77(l), pc(l), cobol(l), or pll(l) manual page, 
as applicable, in the User's Reference Manual for a complete list of options 
available. 



The general options are listed in alphabetical order in the tables that follow. 



c 



Option Name 



-5 



-c 



-cord 



-cpp 



-C 



-C 



-feedback ///e 



~E 



-J) name or 
-Dname-def 



General Compiler Options 



Purpose 



Use the System V compatible include files and librar- 
ies instead of the 4.3 BSD default include files and 
libraries. 

Prevents the link editor from linking your program after 
compilation. This option forces the compiler to produce 
a .o file when you compile only one program. 

Re-arranges the procedures in the link-edit object file 
to reduce cache conflicts in the executable object 
(a.out). At least one -feedback file must be specified. 
See cache conflicts and the -cord option profiling for 
more information. 

Run the C macro preprocessor on the source code before 
compiling. The default varies from driver to driver. Re- 
fer to the appropriate man page (cc, pc, as, etc) in the 
User's Reference Manual for more information. 

C and assembler drivers only. Used with the ~P and 
-E options. Prevents the macro processor from strip- 
ping comments. Use this option when you suspect the 
preprocessor is not emitting the intended code and you 
wish to examine the code with its contents. 

Pascal and FORTRAN drivers only. Generates code that 
causes range checking for subscripts during program exe- 
cution. 

Produces (together with the -cord option) an object with 
procedures rearranged so as to reduce cache conflicts; 
file is the output produce when running -prof with the 
-prof -feedback option specified. See cache conflicts 
and the -cord option for details. 

Runs only the C macro preprocessor and sends results to 
the standard output. Specify also -C to retain com- 
ments. Use -E when you suspect the preprocessor isn't 
emitting the intended code. 

Defines a macro name if you specified a #define in your 
program. Unless you specify a definition name-def 
the compiler defines the name to be "1". 



( 
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General Compiler Options 



Option Name 



Purpose 



-G num 



-I dirname 
-I 

-J 

-k option 

~ko filename 
-nocpp 

-o filename 



num is a decimal number that specifies the maximum 
size in bytes of an item to be placed in the global pointer 
area. The default is 8 bytes. You can raise or lower num 
to control the number of data items placed in these sec- 
tions. See Limiting the Size of Global Pointer Data in 
Chapter 4 for examples of using -bestGnum and its 
related options. 

Compiler searches the current directory dirname, and the 
default directory, /usr/include, in that order for the in- 
clude file. 

When specified in addition to the -I dirname, the com- 
piler searches only dirname and does not search the de- 
fault directory. 

Creates a file suffixed with a .u that contains ucode, an 
intermediate code used by the compiler for internal 
processing. See the Optimization section in Chapter 4 
for examples of using the -j option. 

option is one of the link editor options shown in Table 
1-1 later in this chapter. The driver passes it to the 
ucode loader, which then performs the link action speci- 
fied by option. 

filname is the name of the output file to be created by the 
ucode loader. 

Do not run the C macro preprocessor on C and assembly 
source files before processing. See also the -cpp option. 

Assigns the name filename to the program object. When 
used with the -c option, tells where to leave .o file. The 
default filename is a.out. 

Same as -E options, except puts results in a i file. 
Specify both -P and -C to retain comments. 



General Compiler Options (2 of 3). 
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General Compiler Options 


Option Name 


Purpose 


-pi or -p 

-S 
-std 

-U name 

-V 

~w 


Permits program counter (pc) sampling. This option 
provides operational statistics for use in improving 
program performance. See Chapter 4 for more 
detaiils. 

Note: This option affects only the link editor and is 
ignored by the compiler front ends. When link edit- 
ing as a separate step from compilation,, be sure to 
specify this option if pc sampling is desired. 

Similar to -c ? except produces assembly code in a .s 
file instead of object code in a .0 file. 

Issues a warning message when the compiler finds a 
non-standard feature in the programming language 
of your source program. 

Overrides a definition of a macro name that you speci- 
fied with the -D option, or that is defined automatically 
by the driver. 

Lists compiler phases as they are executed. Use this 
option when you suspect a phase isn't being run as 
you intended. For example, the option might reveal 
that you failed to specify a library required by the 
link editor. For BSD 4.3 users, this option also 
prints resource usage of each phase. 

Prints the version number of the driver and its phases. 
When reporting a suspected compiler problem, you 
must include this number. 

Suppresses warning messages. 



General Compiler Options (3 of 3). 



Byte Ordering Options 



c 



( 



The compiler can produce program objects executable on target machines with 
either a big-endian or little-endian byte ordering scheme. By default, the com- 
piler produces program objects executable on target machines with the same 
byte ordering scheme as the compilation machine. See Appendix D for more 
information on big and little endian byte ordering. 
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When the byte ordering scheme on the compilation machine differs from that on 
the target machine, you must specify one of the options shown in the following 
table: 



Byte Ordering Options 


Option Name 


Purpose 


-EB 


Produces an object file for a target machine 




that uses a big-endian scheme. You 




should use this option when compiling on a 




little endian-machine. 


-EL 


Produces an object file for a target machine 




that uses a little-endian scheme, you 




should use this option when compiling on a 




big-endian machine. 




When working with the symbol table, note that 




the auxiliary table has the same byte ordering 




as the compilation machine. 



Debugging Options 



The table below lists the compiler options available for debugging source code 
using dbx, whose functions and operations are described in Chapter 5. 



Debugging Options 


Option Name 


Purpose 


-go* 

-gl 

-g or -g2 

-*3 


Produces a program object without debugging infor- 
mation. Reduces the size of the program object and 
should be used when debugging is no longer re- 
quired. Retains all optimizations. 

Permits accurate, but limited, source-level debug- 
ging. This option does most optimizations. 

Permits full source-level debugging. These options 
often suppress optimizations that might interfere 
with full debugging. 

Permits full, but inaccurate, debugging on fully opti- 
mized code. Debugger output may be confusing or 
misleading. Specify this option for programs that 
malfunction only after you attempt to optimize them. 


^Default option 
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Profiling Option 



Optimizer Options 



The compiler system permits the generation of profiled programs that, when 
executed, provide operational statistics. This is done through compiler option 
~p (which provides pc sampling information) and the pixie program (which 
provides profiles of basic block counts). See Chapter 4 for details. 

The table below summarizes the options available for program optimization. 
However, to fully understand the benefits of optimization and how the compiler 
achieves optimization, you should read the Optimization section in Chapter 4 
of this manual. You should also refer to the cc(l), f77(l), pc(l), cobol(l), or 
pll(l) manual page, as applicable, in the User's Reference Manual for details 
on the -03 option, and the input and output files related to this option. 



Optimizer Options 


Option Name 


Purpose 


~0 or -02 

-00 

-01* 

-03 


Global optimization. Optimizes within the bounds 
of individual compilation units. This option exe- 
cutes global optimizer (uopt) phase. 

No optimization. Prevents all optimizations, in- 
cluding the minimal optimization normally per- 
formed by the code generator and assembler. 

The assembler and the code generator perform as 
many optimizations as possible without affecting 
compile-time performance. 

Performs global register allocation across the 
bounds of individual compilation units. Executes 
the uld, merge, and uopt phases of the compiler 
system. 


^Default option 





( 



c 



Compiler Development Options 

In addition to the standard options, each driver also has options that you nor- 
mally won't use. These options primarily aid compiler development work. For 
information about how to use these options, consult the appropriate manual 
page— cc(l), pc(l) 9 f77(l), cobol(l), or pll(l)— in the User's Reference Man- 
ual 

Including Common Files (Definition Files) 

When you write programs, often you have common definition files that you 
share among a program's modules. Common files define things like known 
constants or the parameters for system calls (for example, the files that define 
the object file formats). 

Because globally shared things should go in one place, you need a way to put 
these things in a common place. Definition files (often called header files in the 



( 
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C programming language) let you share common information between many 
files in a program. 

Many people call these files Mnclude or "header" files. These files have a "ft" 
suffix. Typically, a manual page from the User's Reference Manual tells you to 
include a specific definition file. 

Each supported language handles these files the same way, and you specify 
these files in your program's source code. 

NOTE: If you intend to debug your program using DBX (Chapter 5), you 
should not place executable code in an include file. The debugger recognizes 
an include file as one line of source code; none of the source lines in the file 
appears during the debugging session. 

You can include files in your program source files in either of two ways: 

1. In column 1 of your source file, type: 

#include "filename" 

where filename is the name of the include file. Because you placed/Ke- 
name within double quotation marks ("), the C macro preprocessor searches 
in sequence the current directory and the default directory I usr I include. 

2. In column 1 of your source file, type: 

#include <filename> 

where filename is the name of the include file. Because you placzd file- 
name between the greater-than and less-than signs (< >), the C macro 
preprocessor skips the current directory and searches only the default direc- 
tory lusrlinclude for the include file. 

C, Pascal, FORTRAN 77, and assembly code can reside in the same include 
files, and then can be conditionally included in programs as required. To set up 
a shareable include file, you must create a .h file and enter the respective code 
as indicated below: 



#ifdef LANGUAGE_C 

**4g — q coc j e 

#endif 

#ifdef LANGUAGE PASCAL 



Pascal code 



#endif 

#ifdef LANGUAGE FORTRAN 



Fortran code 



#endif 

#ifdef LANGUAGE_ASSEMBLY 

«4g MIPS Assembly code 

#endif 
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Link Editor 



NOTE: When you write your program, you need to include the .h file that you 
created. 



This section summarizes the functions of the link editor and how it works. Re- 
fer to the Id(l) manual page in the User's Reference Manual for complete infor- 
mation on the link editor options and libraries. 

The link editor combines one or more object files (in the order specified) into 
one program object file, performing relocation, external symbol resolutions, and 
all the other processing required to make object files ready for execution. Un- 
less you specify otherwise, the link editor names the program object file a.out. 
You can execute the program object or use it as input for another link editor 
run. 

The link editor supports all the standard command line features of other UNIX 
system link editors except System V ifiles. (An ifile holds a description of a 
load module.) 



Running the Link Editor 



You can run the link editor by typing Id on the command line of your shell or 
by using one of the driver commands as described in this chapter in the section 
Linking Objects. The syntax of the Id command is as follows: 

Syntax: 

Id -options objectl [object2 . .objectN] 

NOTE: The assembler driver as does not run the link editor. To link edit a 
program written in assembly language, do either of the following: 

• Assemble and link edit using one of the other driver commands 
(cc, for example). The .s suffix of the assembly language 
source file causes the driver to invoke the assembler procedures. 

• Assemble the file using as, then link edit the resulting object 
file with the Id command. 



Specifying Libraries 
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If you compile multi-language programs, be sure to explicitly load any required 
runtime libraries. For example, if you write your main program in C, and some 
procedures in Pascal, you must explicitly load the Pascal library lihp.a and the 
main library lihm.a with the options -Ip and -Im (abbreviations for the libraries 
libp.a and libm.a), as shown below, when you link these programs. 

% cc main . o more . o rest . o -Ip - 1m 

To find the Pascal library, the link editor replaces the -1 with lib and adds an .a 
after p. Then, it searches the /lib, lusrllib and lusrl local/ lib directories for this 
library. For a list of the libraries that a language uses, see the associated driver 
manual page cc(l), f77(l), pc(l), cobol(l), or pll(l) in the User's Reference 
Manual. 
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You may need to specify libraries when you use UNIX system packages that are 
not part of a particular language. Most of the manual pages for these packages 
list the required libraries. For example, the plotting subroutines require the li- 
braries listed in the plot(3X) manual page; these libraries are specified as fol- 
lows: 

% cc main . o more . o rest . o -Ip - lplot 

To specify a library created with the archiver, type in the name of the library as 
shown below. 

% cc main . o more . o rest . o libf ft . a - lp 

NOTE: The link editor searches libraries in the order you specify. Therefore, if 
you have a library (for example libfft.a) that uses data or procedures from -lp, 
you MUST specify libfft.a first. 



Link Editor Options 



Table 1.1 on the next pages summarizes the link editor options. Refer also to 
the list of general options earlier in this chapter and to the ld(l) manual page in 
the User's Reference Manual for complete information on options and libraries 
that affect link editor processing. 
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Link Editor Options ~ B 


Option Name 


Purpose 


-A/ife 


This option produces an object that may be read into an al- 
ready existing program. The argument, /z/e, is the name of the 
file whose symbol table is used to base the definition of new 
symbols. Only newly linked information is entered into the 
text and data portions of a.out; the new symbol table reflects 
every symbol defined before and after the incremental load. 


-b 


Tells Id not to merge symbolic information entries from 
the same file into one entry for that file. Use this option when 
a file compiled for debugging has variables with the same 
names but different attributes. This can occur when compiling 
two object files that use the same include file, and variables 
with the same name differ because of conditional compilation 
statements within the file. 


-B rium 


Sets the starting address of the uninitialized data segment (bss) 
to the hexadecimal address num. This option is valid only 
when you've also specified the -N link editor option described 
later in this table. 


-Ustring 


Append string to the library name created by the -be or -klx 
option. The library is searched both with and without string. 


-bestGnum 


See -G on the next page. 


-D num 


Sets the starting address of the data segment (data) to the 
hexadecimal address num. This option is valid only when 
you've also specified the -N link editor option. 


-e epsym 


Sets the default entry point address for the output file to the 
specified symbol epsym. 


-EB 


Uses big-endian byte ordering when writing out header 
and symbol table entries. 


-EL 


Uses little-endian byte ordering when writing out 
header and symbol table entries. 


-ffill 


Sets the fill pattern for "holes" within an output section 
of an object file; fill is four-byte heaxadecimal constant 
that defines the fill pattern. 



c 



( 



Table 1.1 (1 of 4). Link Editor Options. 
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Link Editor Options 



Option Name 



Purpose 



-F or -z 



-G num 



-bestGnum 



-count 

-nocount 

-countall 



-jmpopt 
-nojmpopt 



Creates a ZMAGIC file (an object file that loads on de- 
mand) This is the default. See Chapter 10 of the As- 
sembly Language Guide for more information on 
ZMAGIC files. 

Specifies the maximum size (in decimal bytes) of a 
xomm item that should be allocated in the small 
uninitialized data (sbss) section for reference by the 
global pointers. The default is 8 bytes. 

Prints the optimum value to be specified as the num 
value for -G. 

The link editor uses these options in determining which 
objects are to be included or excluded in computing a 
value to be specified in the -bestGnum option. For 
example, you would exclude any object for which you 
did not have the source code for recompilation. The 
options are explained below. 

-count Objects that follow on the command 
line cannot be recompiled. 

-nocount Objects that follow on the command 
line can be recompiled. 

-countall Overrides any -nocount option ap- 
pearing after it on the command line. 

See Limiting the Size of Global Pointer Data in Chap- 
ter 4 for examples of using the -bestGnum and related 
count options. 

Fill or don't fill the delay slots of jump instructions with 
the target of the jump and adjust the jump offset to jump 
past that instruction. Disabled when the -gl, -g2 or -g 
flag is present. When enabled, this option can cause an 
out-of-memory condition in the link editor. 



Table 1.1 (2 of 4). Link Editor Options. 
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Option Name 



-Ix 



-L dirname 



-m 



-M 



-n 



-N 



Link Editor Options 



Purpose 



Specifies the name of a link library, where x is the li- 
brary name. The link editor searches for libxa in /lib, 
/usr/Ub, and /usr/local/iib directories respectively. For 
example, if you specify curses, the library pathnames 
can be; 

Aib/curses.a 

/usr/lib/curses.a 

/usrAocal/lib/curses. a 

If a library relies on procedures or data from another 
library, specify that library's name first. 

If a library resides in a directory other than /lib, /usr/lib„ 
or /usr/local/lib, use the -L option to specify the appro- 
priate directory for that library. 

NOTE; if the byte-ordering (endian) scheme of the ob- 
ject module differs from that of the machine on which 
the link editor executes, the default libraries change. 
See the ld(l) manual page in the User's Reference Man- 
ual for more information. 

Searches dirname for libraries specified in the Ax op- 
tion before searching directories /lib, /usr/lib, and /usr/ 
local/lib. 

This option must precede the -Ix option. 

If the link editor doesn't find the library in dirname, 
then /lib, /usrAib, and /usr/iocal/lib are NOT searched. 
A -L dirname option must be specified with -L, 

Produces a link editor memory map in System V for- 
mat. 

Produces a link editor memory map in BSD format. 

Creates an NMAGIC* file. The text segment is read- 
only and shareable by all users of the file. 

Creates an OMAGIC* file. The text segment isn't read- 
able and shareable by other users. The data segment 
follows immediately; after the text segment. 



*See Chapter 10 of the Assembly Language Programmer's Guide for 
more information on NMAGIC and OMAGIC files. 



( 



Table 1.1 (3 of 4). Link Editor Options. 
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Link Editor Options 


Option Name 


Purpose 


~o filename 


Specifies a name for your object file. If you don't spec- 
ify a name, the link editor uses a.out as the default. 


-pfile 


Preserves the symbol names listed in file when loading 
ucode object files. The symbol names in file are sepa- 
rated by blanks, tabs, or new lines. See Optimizing Fre- 
quently Used Modules in Chapter 4 for an example. 


-r 


Performs a partial link-edit, retaining relocation entries. 
This is required if the object is to be re-link edited with 
other objects in the future. The option causes the link 
editor not to define common symbols and to suppress 
messages on unresolved references. 


-s 


Strips symbol table information from the program ob- 
ject, reducing its size. 


-S 


Suppresses non-fatal error reporting. 


~T num 


Sets the origin for the text segment to the specified 
hexadecimal number. The default origin is 0x400000. 
The contents and format of the text segment are de- 
scribed in Chapter 10 of the MIPS Assembly Language 
Programmer's Guide. 


-u symname 


Makes symname undefined so that library components 
that define symname are loaded. 


-v 


Prints the name of each file as it is processed by the link 
editor. 


-V 


Prints the link editor version number. You might need 
this number, for example, when reporting a suspected 
bug in the link editor. 


-VS num 


Puts the specified decimal version stamp num in the ob- 
ject file that the link editor produces. 


-x 


Retains external and static symbols in the symbol table 
to allow some debugging facilities. Doesn't retain local 
(non-global) symbols. 



Table 1.1 (4 of 4). Link Editor Options. 
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Object File Tools 

The following tools provide information on object files as indicated: 

• odump: lists the contents (including the symbol table and 
header information) of an object file. 

• nm; lists only symbol table information. 

• file: provides descriptive information on the general properties 
of the specified file (for example, the programming language 
used). 

• size: prints the size of the .init, .text, .rdata, f data, .sdata, .lit8, 
Jit4 .bss, and .sbss sections. The format of these sections is 
described in Chapter 10 of the Assembly Language Program- 
mer's Guide, 

The sections that follow describe these tools in detail. 

Dumping Selected Parts of Files (odump) 

The odump tool lists headers, tables, and other selected parts of an object or 
archive file. Figure 1.3 at the end of this section shows some examples of list- 
ings produced by odump and the command that produced each listing. As noted 
in the figure, an explanation of the information provided by odump can be 
found in Chapters 10 and 11 of the Assembly Language Programmer's Guide. 



Syntax: 



c 



( 



odump options filenamel [filename2. . filenameN] 



In the above syntax description, options is one or more of the options and sub- 
options listed in Table 1.2; filename is the name of one or more object files 
whose contents are to be dumped. For more information, see the odump(l) 
manual page in User's Reference Manual. 



c 
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Main odump Options 


Option Name 


Purpose 


-a 


Dumps the archive header of each member of the 
specified archive library file. 


-c 


Dumps the string table 


-f 


Dumps each file header. 


-F 


Dumps the file descriptor table. 


-g 


Dumps the global symbols in the symbol table of 
an archive library file. 


-h 


Dumps the section headers. 


-i 


Dumps the symbolic information header. 


-1 


Dumps line number information. 


-0 


Dumps each optional header. 


-P 


Dumps the procedure descriptor table. 


-r 


Dumps relocation information. 


-R 


Dumps the relative file index table. 


-s 


Dumps the section contents. 


-t 


Dumps symbol table entries. 


-L 


Interpret and print contents of the .lib sections. 



Table 12 (1 of 2). Odump Options. 
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Auxiliary odump Options 


Option Name 


Purpose 


-d number 


Dumps the section number, or a range of section 
numbers, that starts at the specified number and 
that ends with the last section number or the 
number you specify with the +d auxiliary option. 


+d number 


Dumps the sections in a range that starts with the 
first section or with the section you specify with 
the -d option. 


»n name 


Dumps information only for the named entry 
name. Use this option with the -4i, -s, -r, -1 and 
-t options. 


»p 


Suppresses the printing of headers. 


-t index 


Dumps only the indexed symbol table entry. You 
can specify a range of table entries by using the 
~t option with the +t option. 


+t index 


Dumps symbol table entries in a range that ends 
with the indexed entry. The range begins with 
the first symbol table entry or with the section 
that you specify with the -t option. 


^v 


Dumps information in symbolic rather than nu- 
meric representation (for example, in Static rather 
than 0X02). Use this option with all dump op- 
tions except -s. 


-z name,number 


Dumps the line number entry or a range of entries 
that start at the specified number for the named 
function. 


+z number 


Dumps the line number that starts at the function 
name or the number specified by the -z option 
and that ends at the number specified at the +z 
option. 



Table 1.2 (2 of 2). Odump Options 



( 
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, ' '***STRING <TABLE INFORMATION** * 




[Offset} 


^i^^^Rl^^j^^^H^^^^^^^Pl^PS^^S^l^^^BHIHi 




sam.o: 

:v: : : : :v: : : ; : : : : : : : : : : x<-:v; : : ; : : : : ;':f: : n : : : ~' : " : ; : :v: x : : :-: : : : : ::: : : >:v; : : : : : : : 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^i^K. 




[1] 


sam*C 








[7] 


-line 


% odump -c sam.o 






[121 
'[191 


s 4 : rLtiQ 








length ' 






[26] 


linenxmibex , 




[37] 


LINEUP El 




[461 


^^^^ii^BK^^^^^^^^^^^^^^^^^^^KI^^BlllllllBi^i 




[51] 


lll^^^^^RP^^^^^B^^^^^I^§l^iMlHi^Pi^8^illlll^^lli 




1567 


^Pij^l^^^^^^^^MlMil^lM^^^Bii^Bll^^^RlPl 




[611 ' 


^WB^^^^^^^^^^^^^^^^^^^B 




[671 


IWili^^^^^^^^^^^^^^^i^^R^^^^^lifll 




[707 


^^^^^^^^^^^^^^^^^^^^^^^^^^tt 




[•721 


liffi^^^^B^^^^^^R^^^^^^^^^B^^^^^^^^I^^^lSffii:^ 




[741 


Curlinsnumbe-r 




[881 ■• • 


Printline 




[981 


:||§|i|j||^ 




[1043 


II^^^^^^^B^BB^^^^^K^^^^BW^^Si^^Blllllli^lisii 




[107] 


/u6r/lacal/rrtif33/in<^lude/stdio.h 




' J139J .. 


_iobuf 




[1463" ' 


"^^^^^^^^^^^^^^^^^^^^^^^^K^^^^K^^^^^P 




[151] 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^BS 




[1563 ' 


!!!!;§||'!;I1!1 




[1623 


|||^i^^^:lP^RIHP^^^^^i^^^^l^^l^^^l^^^^8Bi:i 




[1703 


I^^Pl^^^^^^^^^^^^^^^^BllPlfi^lS^^llP^il^SHi^ll 




:||lllliIS;illiilIl 


|||l||iii;llll|l|lllllllil|;l 




[1823 


llll|||^ 






T»w»w*ww«wwt n-rrrr. — nr-i—ci rr rm 








***FX1& HEADER*** 


% odump 


-f sam.o 




:$S:*i$^ 








M#g±c 


^50n^ 1»ime /Date Syraptr' Mgyms Opt hdr 


£\lag$ 


sam»o: , 






C000540 


2 '{)4f22b375 0x00000344 96 0x0038 


0x0000 




% odump -F 


sam.o 


***£11,E t>£SCRI£!T0R T 






filename < ■ 


"1 TV/*V'f : 'H? O.O 4* w i^t n-rn-r tr w 


^<Jdre$9 ' cbLin^ gym line p<J aux rfd 


n«r3- r Q. Ci 3 ^ 2t 

language 


sam + o: 






$anu q 


0x000 00000 


el 




. . 23 27 103 2 40 


ilEiRtiii 


P$/include/^t'diQVh'OiO.O.O'0O00p 27 2 40 


merge el 




< . 11 36 


c • 


For an explanation of the contents of this listing, see Chaj 


tfpi'c 1|| o n H 1 | 




}%.%,& ■» 1.1/ ullii 11, 




of the Assembly Language Programmer's Guide, 





Figure 13 (1 of 4). Example of Odump Utility Output (partial). 
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sam.o; 



|!!i|p||||| 

liliiiiliil 



***SECTTCN HEADER*" 

" ' " ' Vaddr 



% odump -h sam.o 



•paddri 

iliiii 



Scrtptr 



Rfelptr 



• Lrmoptr 

illllilll 



0x00000 D00 OxODOOO 000 0x0 0000 09c 0x0 000027c 0x0 0000000 

0x0 0000020 0x0 0000 l&O 25 

0x0 0000 1&0 OxOOOOOl'aO 0x0000053c 0x00000344 OxOGOOODOO 

0x00000200 0x00000040 



**'*s^mbclic iiiiiiiiiii iiiiiiiiii 



% odump -i sam.o 



CbLine 

sarrwo: 
.• OxCOIS 



1111 



liilii 



—————— iMax/C;bOffS^t————^ 

fd _ liti^ atritij 5ym xatrirt^! 



Ililil 
lillil 



111 



iii 
iiii! 



lilill 
llllll 



llllll 



|di|: 



?i;£;di! : ! 



lilill 



12- 

2232 



illx 



■ S 

111:1 



***LIfcJE NUMBER INFORMATION*** 
Symndx/Paddr Lnno 



M^^oi;::; 



% odump -I sam.o 



Lia^5 for file 3am + c; 

Q, 17 l', 17 2, 

3, 17 4, 17 • 5, 

€, 24 7, -24 8, 

9, 25 10, 25 11, 

12, 25 , '13 «' 26 14, 

15, 2 6 15, 2 6 17, 

18, 27 19, 30 20* 



11 

: 24 

llll 

mm 

iiill 
ill;: 



***0£>fXOtfAt> JffiA&£R in REX*** 



3am, o; 



% odump ~o sam.o 



010? 001b OlaO 0000 0040 0000 0000 oooo oooo 0000 oooo oooo 
QlaO 0000 01^0 0000 fff 6 1>301 0000 oooo 0000 0000 oooo oooo 
000 0000 8190 0000 



i:;;&"@¥R=®;;; : 



* * - PROCEDURE DESCRXJP^OR ¥ABL£** * : 
Iiiiiiiiii;;! 



% odump -P sam.o 



mmMmwwmmWm 








^;&m?WW&Mmm$M 


f0 ior 2] 






ma i n w: ^.av*::*? , 


0x00 000 


mmmm 


iiii: 






iiiiil 


i§i« 


print j ixie 


0x00000138 


20 


;:;:;:;«;§; 






«II 


•58 



/usr/loc^l /mips/ include/ 5^'di<? + h J 2 for 03 



isym iline iopt r^graask regoff fpoff fp 
InQf f9Qtt InLow InMigh. f regmasJc f rgof f 



-1 -0x8003 0000 -264 304 29 

51 0x0000 0000 31 

-1 0x80000000 -12 40 2 9 

€3 ' 0x00000000 • G 31 



For an explanation of ihe contents of this listing, sec Chapters 10 and 11 
of the Assembly Language Programmer' '$ Guide, 



Figure 1.3 (2 of 4). Example of Odump Utility Output (partial). 
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, text : 


Vaddr ' ' Symndx Typ& Extern 

0x000 0034 1 Q 4 
0x000 00038 1 5 
0x000 0040 4 6 
0x000 Q003c 1 8 • 3 
0x000 0004 4 1 g • 3 
0x00000050 4 -6 
0x000 00058 1 1. 3 
, 0x0000007 8 1 4 


^■*** 






% odump -r sam.o 








0x0 00 0Q07c 
.0x00000088 

0x000 0006 4 


mmmm. 
lillili 


4 

1111111 


5 
6' 

llillili 








OxOOOGOOSc 


iiiiii; 


a 


3 








0x0000009c 
0x000 QOOac 
0x000 000&C 
OxOOOOOOfc ' 


liiiiii 
0' 

liiiiii 


10 • •' 
4 

wmmm 


iill • 

.3 •' 

iiiiiiii 

llliilil 








0x00000100 


iiiiiiii 


iiiiii 
lllllll 


3 
3 ' 








Ii:;ill:;::0llil:!0ll!|illlli| 


-I':"'-- 


liiiiii 


4 

liiiiii 








• 0x00000168 ' : 

0x000 017 • 
!ll;i;:|!:0iliiii;iliil!lill; 
0x00000180 
0x0000017c 


o- 

•1 

1 


4 

iiiiii 
liiiiii 
iiiiii 
ii 


mmmm 
liiiiii 

4 

5 '• " 

iilliii 






||||1|||^ 


***RELA3MV£ FILE mmX STABLE 

sanu c [0- for 0] 

/^3 r/locaiymip^/ include /9tdio-hJ|0 for 03 


.*** 










% odump -R 


sam.o 


















lllllllllillllllilll 










[iilll 


% odump -s sam.o 




s an . o : ' 














Si!:'::^ 






, text ; 

' '• • 2 7BD 

1111 

0000 

• 2004 

AFA2 

wmmmSim 
llllllillll 


FEDO MSF 0014 

00 CO afah; 002 

liliillllllllllllllill 

ioiiii!iiiiii;i«iiiii 

002 4 8FB9 002 4 

0000 2424 0030 

0001 27A4 0028 


liiiiii 

iiiiiill 
•2424 

•27 85 

iillil 

iliili 

iiii 


0130 

iiiiii 

lliliill 

iiiiliill 

iillil 

0004. 
0024 


ilillii 

liiiiii 

8F04 
1720 

mmmm 
ocoo 


013 4 AFB0 0010 

o.6:0 029^100 02 

000 2 7 85 8010 

iiiiiiiiiiiiiillii! 

m&Mmmmmms. 
W$mmm§mm<mm 
m$$m^mmmm& 


8FAB 0130 
1020 0007 ' 

OCOO oooo. 

0000 OOOO 
iiiiiiileiiiiillii 

wmmMmmMimm 
mmmmmmmm 


of the Assembly Language Programmer's Guide, 



Figure 1.3 (3 of 4). Example of Odump Utility Output (partial). 



Languages Programmer's Guide 



1-25 



Chapter 1 









***SYMBOL 


TABLE INFORMATION*** 




[Index] 
sam.o: 
[0] 
[1] " 


|:|||:|i|:i|||||||| 


Value, 


Sclavs 


Symtype 


Ref 




•. sarruc 


OxQ'C 

iiiiiit 


ililll 


OxOl 


OxOb 


QxOOlb 




Itlllll 


llililill 


lilt 


0x00 6 




12} ■ 


string 


Ixllililli 


m&mmm 


0x0 9 


0x0 OOe 




[3] 


length 


llililliliilililiii: 


■ MM 


1x11 


OxO'004 




[4] 


linenumba 


rzOxQOO0O820 


'mmmmm 


iiliil;iixli;i!lii!iillii;i! 


0x0004 




ill 

[6] 




lllllilill 


■ OxOb 


Iill 


0x0001 




L1NETYPE 


0x0 000 00 


0x0b 


«&lt$iliilt^ 


0x0013 




[7] 
[8] 


:: '^'ma;in;:;l'V''-9-|; 


iiiiliiillili; 


wmmmim 


0x06 


0x0017 




argc 


iiii§§i§lll§ii;i 


0x05 


0x03 


0x0004 - 




[9] 


argv 


ixlllllill 


0x05 


0x03 


0x0019 




: [10] 




0x00000014 


0x02 


ili|;i;iilliillill! 


0x0013 




: [11] 


;xii;:iil:i:Bl:!:ii;i;:ii!i|i 


i:iillliili§;ii 


0x05 


0x0 4 


0x001a 




[12] 


fd 


0xfffffef4 


lili;ll«;i 


0x04 


0x001c 




[13] 


llli:|||||ll;:lll;lll 


OxfffffefO 


. :y --:oxosm 


llll!lllll:lii!llii;i;l; 


0x0004 




[14] 




iiiiiliiiiiii 


oxoi 


0x07 


llllllllillllllll; 




[15] 


i 


OxfffffeeS 


0x05 


0x0 4 


0x0004 




[16] . 


cur 1 in e numb e c k 00 0.0 lc 8" - C ' •'• ?;• .0 x Oc ; :•: ;v ? : : : ■'. : ' x0 2 •• : :=: ;• 


0x0004 




[17] 




^61;9i!0l ! e©:iiQ : :8 ; »i:; 


• 0x01 • 


• 0x0 8 


OxOOOe 




[1&] 




iiiliiiiiiillilii! 


OxOl 


wmmmmmm 


OxOGOa 




[19] 


main 


llilllililllll 


0x01 


0x08 


liliiillilillllll 




[20) 
[21] 
[22] 
[23] 


Printline 
pline 

i 


OxQj 


tftfi^x^Rx*:; 


wm0m&w* 


.0x06 

0x03 

1 0x04 


0x0015 
0x0024 
0x0019 
0x0004 




0x0 
0x0 


Vo odump - 


-t sam.o 


Oxf 


bp^^ifi^ixi: 


■m&M&M&M 


[24] 




0x000v004o 


iiiiiiii;:; 


^MWJ^B 


0x0016 




[25] 


Printline 


ijfciisiijiiiiiii 


OxOl 


^M^I^^H 


mrnm^mmmm 




[2 6] 


sarmc 


0x00000000 


llililill 


llllllilllilliill 


0x0000 




[27] 


/usr/looa 


l/mip$/include/atdiQ, 


hOxOOOOOOOO 


0x01 0k 


Ob 0x0026 


[28] 


iobuf 


0x00000018 


OxOb 


0x07 


0x0025 




[29] 


|||;|i i 


iiiiiliiiililliiii; 


OxOb 


0x09 


0x002c 




1301 


iill 


iiiilliiiiOiillliill 


lliiiiliit 


0x09 


0x0036 




[31] 


_base 


liilliilll 


OxOb 


0x09 


0x0037 • 




[32] 


buf $1 2 


0x00000060 


OxOb' • 


0x09 


0x002c 




[33] 


"flag 


liifliiliiii 


liililiii 


0x0 9 


0x002b 




[34] 


_file 


0x00000090 


OxOb 


0x09 


.0x0030 




[35] 


^_name 


OxOOOOOOaO 


0x0b 


OxC 9 


0x0038 




[36] 




mmm&mmmi 


OxOb 


0x0 8 


0x001c 




[37] ; • 


/usr/ local/mips /inqlu 


de/stdio 


lllilllllilil 


0x:01 ' 0* 


OB 0x0 01b 


immmB 


^iob 


mmmmmm 


■ oxis: 


mml^&mmmi 


0x0039 




[39] 


f open 


OkCCOCO'000 


0x0 6 


wmmmmmm 


0x003f 




[401 


f do pen 


0x00000000 


0x00 • 


iiiiiiliiiiii 


0x0035 




[41] 


lilliiiilliipiiiilll 


illllilllllllil 


0x00 


Iill 


0x0038 




[42] ■ 


ftell 


liilliilll 


0x00 


iiiiiiliiiiiii 


0x003b 




[43] . 


fgets 


iliiiliiiil! 


mmmmm 


0x06' 


0x00 4a 




[44] 


Printline 


iliilllillii 


• 0x01 • 


itillliiilti;s 


0x0014 




[45] 


• main . • 


0x00000000 


0x01 • 


wmmmmmm 


'0x0007 




[46] 


f print f 


0x00000000 


iiiiiiii 


0x06 


OxOOle 




[47] 


exit 


0x0 00 OC- 00 


0x0 6 


0x0 6 


0x0020 




[48] 


3trlen 


iilllltlllli 


0x0 6 


iiil0lSii:«i; 


0x0022 




[49] 


f flush 


lilllllllllll! 


iiiiiiii 


0x06 


0x002 6 




For an explanation of the contents of this listing, se 


*e Chapters 10 and 11 




of the Assembly Language Programmer" s Guide, 









( 



( 



Figure 13 (4 of 4). Example of Odump Utility Output (partial). 
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Listing Symbol Table Information (nm) 

The nm tool prints symbol table information for object files and archive files. 
Syntax: 



nm options filenamel [filename2. . filenameN] 



In the above syntax description, options is one or more of characters (listed in 
Table 1.4) that specify the type of information to be printed; filename specifies 
the object file(s) or archive file(s) from which symbol table information is to be 
extracted. If you don't specify a file, nm assumes a.out. 

Below is an example of an nm statement and the listing it produces. Note that 
each item in the listing has a key that describes its storage class. The keys are 
explained in Table 1.3. 

Examples: 



%nm a . out 


00004608 


S Argc 


0000460c 


S Argv 


00004490 


d blanks 


00004700 


b bufendtab 


00003330 


T cerror 


00000cd4 


T cleanup 


000044e8 


D ctype 


OOOOlfaO 


T doprnt 


00000de4 


T exit 


00001878 


T filbuf 


00000990 


T filbuf 


0000c560 


N gp 


00004228 


D iob 


00004598 


G lastbuf 


00001f44 


t lowdigit 

* 1" 


1 

value 


T T 

| symbol 


field 


name 


key (see Table 1.3) 



Figure 1.4. Symbol Table in BSD Format (option -B) 
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The meanings of the character keys shown in an nm listing are described below. 



Key 


Description 


N 


Nil storage class, which avoids loading of un- 
used external references. 


T 


External text. 


t 


Local text. 


D 


External initialized data. 


d 


Localinitialized data. 


B 


External zeroed data. 


b 


Local zeroed data. 


A 


External absolute data. 


a 


Local absolute data. 


U 


External undefined data. 


G 


External small initialized data. 


S 


External small zeroed data. 


s 


Local small zeroed data. 


R 


External read-only data. 


r 


Local read-only data. 


C 


Common data. 


E 


Small common data. 




External small common data. 



c 



c 



Table 1.3. nm Character Key Meanings. 



( 



1-28 



Languages Programmer's Guide 



The Compiler System 



Symbols from sam.o: 










Name 


Value 1 Class 1 


Type 


Size 


Indx Section 


sam. c 


00000000 |File 


ref=27 




I | Text 


line 


00000264|Block 


ref=6 




1 l|Info 


string 


00000000 | Member 


unsigned 


char [256] | 


I 2 | Info 


length 


00002048 |Member 


int 




I 3| Info 


linenumber 


00002080 iMember 


int 




I 4 | Info 




OOOOOOOOIEnd 


ref=l 




1 5 | Info 


LINETYPE 


00000000 iTypdef 


struct line | 


1 6 j Info 


main 


00000000 |Proc 


end=20 int j 


I 7 | Text 


argc 


00000000 iParam 


int 




1 8|Abs 


argv 


00000004|Param 


unsigned 


char ** | 


1 9|Abs 




00000020 iBlock 


ref=19 




I 10| Text 


linel 


-0000264|Local 


struct line | 


I ll|Abs 


fd 


-0000268 lLocal 


struct _iobuf* | 


I 12|Abs 


i 


-0000272 |Local 


int 




I 13|Abs 




00000172 IBlock 


ref=18 




I 14| Text 


i 


-0000280 lLocal 


int 




I 15|Abs 


curlinenumber 


00000456|Static 


int 




I 16|SData 




00000264|End 


ref=14 




I 17 | Text 




00000288 |End 


ref=10 




1 18| Text 


main 


00000312 |End 


ref=7 




I 19| Text 


Printline 


00000312 |Proc 


end=2 6 btNil | 


1 20| Text 


pline 


00000000 IParam 


struct line* | 


1 21|Abs 




00000012 IBlock 


ref=25 




I 22| Text 


i 


-0000004 lLocal 


int 




I 23|Abs 




00000076|End 


ref=22 




I 24 | Text 


Printline 


00000100 |End 


ref=20 




I 25 I Text 


sam.c 


00000000 JEnd 


ref==0 




I 26| Text 


/us r/ local /mips /incl 


00000000 IFile 


ref=38 




I 27| Text 


_iobuf 


00000024|Block 


ref=37 




1 28| Info 


_cnt 


00000000 IMember 


int 




1 29| Info 


_ptr 


00000032 IMember 


unsigned 


char * | 


1 30| Info 


_base 


00000064 IMember 


unsigned 


char * j 


I 31| Info 


buf siz 


00000096 IMember 


int 




I 32| Info 


flag 


00000128 IMember 


short 




1 33| Info 


_file 


00000144 IMember 


unsigned 


char j 


1 34| Info 


_name 


00000160 IMember 


unsigned 


char * | 


I 35| Info 




00000000 |End 


ref=28 




I 36| Info 


1 For information on thes 


e fields, see Chapter 11 


in the Assembly Language 




Programmer' s Guide. 











Figure 1.5. Symbol Table in System V Format (option -A).. 
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nm Options 


Option Name 


Purpose 


~A 


Prints the listing in System V format. The 
default format is that of your operating system. 


-B 


Prints the listing in BSD format. The default 
format is that of your operating system. 


-a 


Prints debugging information (turns BSD 
output into System V format). 


-b 


Prints the value field in octal. 


-d 


Prints the value field in decimal (the 
default for System V output). 


~e 


Prints only external and static variables. 


-h 


Suppresses printing of headers. 


-n 


Sorts external symbols by name for System V 
format Sorts all symbols by value for 
Berkeley format (by name is the BSD 
default output). 


-o 


Prints value field in octal (System V output). 
Prints the filename immediately before 
each symbol name (BSD output). 


-P 


Lists symbols in the order they appear in the 
Symbol table. 


-r 


Reverses the sort that you specified for 
external symbols with the -n and -v 
options. 


-T 


Truncates characters in exceedingly long symbol 
names; inserts an asterisk as the last character of the 
truncated name. This may make the listing easier to 
read. 


-u 


Prints only undefined symbols. 


-V 


Sorts external symbols by value (default for Berkeley 
format). 


-V 


Prints the version number of nm. 


-X 


Prints the value field in hexadecimal. 



Table 1.4 Symbol Table Dump (nm) Options. 



( 
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Determining a File's Type (file) 

The file tool lists the properties of program source, text, object, and other files. 

This tool often erroneously recognize? command files as C programs. It does 
not recognize Pascal or LISP programs. For more information, see the file(l) 
manual page in User's Reference Manual 

Syntax: 



file filnamel [filename2. . .filenameN] 



Example: 



% file test.o a. out 

test .ormipsel demand paged pure executable not stripped 

a. out: mipsel demand paged pure executable not stripped 



Determining a File's Section Sizes (size) 



The size tool prints information about the text, rdata, data, sdata, bss, and sbss 
sections of the specified object or archive file(s). The contents and format of 
section data are described in Chapter 10 of the Assembly Language Program- 
mer's Guide. 

Syntax: 



size options filenamel [filename2 . .filenameN] 



In the above syntax description, options is in alphabetic character (listed in Ta- 
ble 1.5) that specifies the format of the listing; filename specifies the object or 
archive file(s) whose properties are to be listed. If you don't specify a file, size 
assumes a.out. 



Below is an example of a size statement and the listing it produces. 
Example: 



% size test.o 

text data bss dec hex 

16384 4096 164437 184917 2d255 
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Size Options 


Option Name 


Purpose 


-A 


Prints data section headers in System V format. 
The default format is determined by the UNIX 
version running at your installation. 


-B 


Prints data section headers in Berkeley format. 
The default format is determined by the UNIX 
version running at your installation. 


~d 


Prints the section sizes in decimal. 


-0 


Prints the section sizes in octal. 


-V 


Prints the version of size that you are using. 


-X 


Prints the section sizes in hexadecimal. 



( 



Table 1.5. Size Options. 



Archiver 



An archive library is a file that contains one or more routines in object (.o) file 
format; the term object as used in this chapter refers to an .o file that is part of 
an archive library file. When a program calls an object not explicitly included 
in the program, the link editor (Id) looks for that object in an archive library. 
The editor then loads only that object (not the whole library) and links it with 
the calling program. 

The archiver (ar) creates and maintains archive libraries and has the following 
main functions: 

• Copying new objects into the library 

• Replacing existing objects in the library 

• Moving objects about the library 

• Copying individual objects from the library into individual ob- 
ject file. 

The sections that follow describe the syntax of the ar (archiver) command and 
some examples of how to use it. See the ar(l) manual page in the UNIX User's 
Reference Manual for additional information. 



( 



( 
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Examples 



Syntax: 



ar options [posObject] libName [objectl . . .objectN] 



The following explains the parameters in the above syntax description: 

• options is one or more characters (listed in Tables 1.6 and 1.7) 
that specify the action that the archiver is to take. When you 
specify more than one option character, group the characters 
together with no spaces between; don't place a dash (-) charac- 
ter before the option characters. 

• posObject is the name of an object within an archive library. It 
specifies the relative placement (either before or after posOb- 
ject) of an object that is to be copied into the library or moved 
within the library. A posObject is required when the m or r 
options are specified together with the a, b, or i suboptions. 
Example 4 below shows the use of a posObject parameter. 

• libName is the name of the archive library you are creating, up- 
dating, or extracting information from. 

• object is the name object(s) or object file(s) that you are ma- 
nipulating. 



1. Create a new library and add routines to it. 

% ar cr libtest.a mcount.o monl.o string. o 

Options c suppresses archiver messages during the creation process. Op- 
tions r creates the library libtest.a and adds mcount.o, monl.o, and string. o. 

2. Add or replace an object (.o) file to an existing library. 

% ar r libtest.a monl.o 

Option r replaces monl.o in the library libtest.a. If monl.o didn't already 
exist, the new object monl.o would be added, 

CAUTION: If you specify the same file twice in an argument list, it ap- 
pears twice in the archive. 

3 . Update the library ' s symdef table. 
% ar ts libtest.a 

Option s creates the symdef table and t lists the table of contents. 

NOTE: After you create or change a library, you must always use the s 
option to update the symdef (symbol definition) table of the archive library. 
The link editor uses the symdef table to locate objects during the link proc- 
ess. 
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4. Add a new file immediately before a specified file in the library. ^ 



ar rb mcount . o libtest.a new.o 



t 



posObject 

Option r adds new.o in the library libtest.a. Option b followed by posOb- 
ject mcount.o causes the archiver to place new.o immediately before 
mcount.o. 

Archiver Options 

The table below lists the archiver options. You must specify at least one and 
only one of the following options: d, m, p, q, r, or x. In addition, you can op- 
tionally specify the c, 1 ? s, t, and v options, and any of the archiver suboptions 
listed in the following tables. 



( 



( 
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Archiver Options (Part 1) 



Option Name 



Purpose 



m 



q 



Suppresses the warning message that the archiver 
issues when it discovers that the archive you 
specified doesn't already exist. 

Deletes the specified objects from the archive. 



Puts the archiver' s temporary files in the current 
working directory. Ordinarily the archiver puts 
those files in /tmp. This option is useful when 
/tmp is full. 

Moves the specified files to the end of the ar- 
chive. If you want to move the object to a spe- 
cific position in the archive library, specify an a, 
b or i suboption together with the posObject pa- 
rameter. 

Prints the specified object(s) in the archive on the 
standard output device (usually the terminal 
screen). 

Adds the specified object files to the end of the 
archive. An existing object file with the same 
name is riot deleted, and the link editor will 
continue to use the old file. This option is 
similar to the r option (described below) but it 
is faster. Use it when creating a new library. 

Adds the specified object files to the archive. 
This option deletes duplicate objects in the ar- 
chive. If you want to add the object at a specific 
position in the archive library, specify an a, b, or 
i suboption together with the posObject parame- 
ter. See Example 4 in the preceding section for 
an example of using the posObject parameter. 

See also the u suboption 

Use the r option when updating existing libraries. 



Table 1.6 (1 of 2). Archiver Options. 
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Archiver Options (Part 2) 


Option Name 


Purpose 


s 
t 

v 
X 


Creates a symdef Tile in the archive. You must 
use this option each time you create or change 
the archive library. 

If all objects don't have the same endian byte 
ordering scheme, the archiver issues an error 
message and doesn't create a symdef table. At 
least one of the following options must be speci- 
fied with the s option: m, p, q, r, or t. 

Prints a table of contents on the standard output 
(usually the screen) for the specified object or 
archive file. 

Lists descriptive information during the process 
process of creating or modifying the archive. 
When specified with the t option, produces a ver- 
bose table of contents. 

Copies the specified objects from the archive and 
places them in the current directory. Duplicate 
files are overwritten. The last modified date is 
the current date, unless you specify the o subop- 
tioa Then the date stamp on the archive file is 
the last modified. 

If no objects are specified, copies all the library 
objects into the current directory. 



( 



( 



Table 1.6 (2 of 2). Archiver Options. 



( 
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The archiver has these suboptions: 



Archiver Suboptions 


Suboption Name 


Use with,.. 


Purpose 


a 


m or r 


Specifies that the object file follow 
the posObject file you specify in the 
ar statement. 1 


b 


m or r 


Specifies that the object file precede 
the posObject file you specify in the 
ar statement. 1 


i 


m or r 


Same as -b 1 . 





X 


Used when extracting a file from 
the archive to the current directory. 
Forces the last modified date of the 
extracted file to match that of the 
archive file. 


u 


r 


The archiver replaces the existing 
object file when the last modified 
data is earlier (precedes) that of the 
new object file. 


See example 4 in the Examples section preceding this section for an 
example of the posObjeci parameter. 



Table 1.7. Archiver Options. 
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Storage Mapping 



C Language 



This chapter describes the alignment, size, and value ranges for the C and Pas- 
cal languages, and how the compiler groups these records in storage. 



This section describes how the compiler maps C variables into storage and con- 
tains the following topics: 



• Alignment, Size, and Value Ranges 

• C Arrays, Structures, and Unions 

• Storage Classes 
Alignment, Size, and Value Ranges 



Table 2.1 describes how the C compiler implements size, alignment, and value 
ranges for the data types. 









Value Range 


Type 


Size 


Alignment 


Signed 


Unsigned 


Int 
long 

enum 
short 

char 4 
float 5 
double 6 
pointer 


32 bits 
32 bits 
1 6 bits 

8 bits 
32 bits 
64 bits 

32 bit 


Word 1 
Word 1 
Half word 2 

Byte 
Word 1 
Doubleword 3 

Word 1 


-2 31 to2 -1 31 
-2 31 to 2 31 - 1 
-32,768..32,767 

-128..127 
See note. 
See note. 


0to2 32 -1 

0..65.535 
0..255 

to 2 s2 -1 


1 Byte boundary divisible by four. 

2 Byte boundary divisible by two. 

3 Byte boundary divisible by eight. 

4 char is assumed to be unsigned, unless the signed attribute is used. 

5 IEEE single precision. See note following this table for valid ranges. 

6 IEEE double precision. See note following this table for valid ranges. 



Table 2.1. Size, Alignment, and Value Ranges for C Data Types. 
NOTE: Approximate valid ranges for float and double are: 
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Maximum Value 


float 
double 


3.40282356*10 38 
1.7 97 6931348 623158*10 308 



( 





Minimum Values 




Denormalized 


Normalized 


float 
double 


1.40129846*10~ 46 
4.940 6564584124 654*lCf 324 


1.17549429*10~ 38 
2, 2250738585072012 *1.5 308 



For characters to be treated as signed, either use the compiler option — signed, 
or use the keyword signed in conjunction with char, as shown in the following 
example: 

signed char c; 

The header files limits. h and float.h (usually found in /usr/include) contain C 
macros that define minimum and maximum values for the various data types, 
Refer to these files for the macro names and values. 

The following sections describe how the data types shown in Table 2,1 affect 
arrays, structures, and unions. 

C Arrays, Structures, and Unions 

Arrays, Arrays have the same boundary requirements as the data type specified 
for the array. The size of an array is the size of the data type multiplied by the 
number of elements. For example, for the following declaration: 

double x[2] [3] 

the size of the resulting array is 48 (2*3*8, where 8 is the size of the double 
floating point type). 

Structures. Each member of a structure begins at an offset from the structure 
base. The offset corresponds to the order in which a member is declared; the 
first member is at offset 0. 

The size of a structure in the object file is the size of its combined members 
plus padding added, where necessary, by the compiler. The following rules ap- 
ply to structures: 

• Structures must align on the same boundary as that required by 
the member with the most restrictive boundary requirement. 
The boundary requirements by degree of restrictiveness are: 
byte, halfword, word, and doubleword, with doubleword being 
the most restrictive. 

• The compiler terminates the structure on the same alignment 
boundary on which it begins. For example, if a structure begins 
on an even-byte boundary, it also ends on an even-byte bound- 
ary. 



( 



( 
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For example, the following structure: 

struct s { 
int w; 
char n [10] ; 

is mapped out in storage as follows: 



Big Endian 




V 


V 


V 


V 


nO 


n1 


n2 


n3 




Byte 


12 3 4 5 6 7 






n4 


n5 


n6 


n7 


n8 


n9 


tl-;§£l:t:f: 


:|||1| 




Byte 8 9 10 11 12 13 14 15 
Little Endian 




| 


lllHH n9 


n8 


n7 


n6 


n5 


n4 




Byte 


15 14 13 12 11 10 9 1 


3 




n3 


n2 


n1 


nO 


V 


V 


V 


V 




Byte 

7 6 5 4 3 2 10 

H Padded bytes 





See Appendix C for more information on big and little endian byte ordering. 

Note that the length of the structure is 16 bytes, even though the byte count as 
defined by the int v and the char n components is only 14. Because int has a 
stricter boundary requirement (word boundary) than char (byte boundary), the 
structure must end on a word boundary (a byte offset divisible by four). The 
compiler therefore adds two bytes of padding to meet this requirement. 

An array of data structures illustrates the reason for this requirement. For ex- 
ample, if the above structure were the element-type of an array, some of the int 
v components wouldn't be aligned properly without the two-byte pad. 
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Alignment requirements may cause padding to appear in the middle of a struc- 
ture, For example, by rearranging the structure in the last example to the fol- 
lowing: 

3truct s { 

char n[10] 

int w; 
} 



( 



the compiler maps the structures as follows: 



Big Endian 



nO 


n1 


n2 


n3 | n4 


n5 


n6 


n7 



Byte 12 3 4 5 6 7 



n8 


n9 


11111 




V 


v 1 V 



Byte 8 9 10 11 12 13 14 15 



Little Endian 



Byte 



Byte 



V 


V 


V 


V 


■Bill 


n9 


n8 


15 U 


t 13 12 11 10 9 8 


n7 


n6 


n5 


n4 


n3 


n2 


n1 


nO 



5 4 



1 



B Padded bytes 



Note that the size of the structure remains 16 bytes, but two bytes of padding 
follow the n component to align v on a word boundary. See Appendix C for 
more information on big and little endian byte ordering. 



c 



( 
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Bit fields are packed from the most significant bit to least significant bit in a 
word and can be no longer than 32 bits; bit fields can be signed or unsigned. 
The following structure: 



typedef struct { 

unsigned of f set :12; 

unsigned page 

unsigned segment : 9; 

unsigned supervisor : 1; 
} virtual address; 



:10 



Big Endian 



Byte 






3 








offset 


page 


segment 




Bit 31 




9 




9 


1+ 



supervisor 



Little Endian 

Byte 3 



Bit |30 
supervisor 





segment 


page 


offset 



22 



12 



is mapped out as follows: 

The compiler moves fields that overlap a word boundary to the next word. See 
Appendix C for more information on big and little endian byte ordering. 

The compiler aligns a nonbit field that follows a bit-field declaration to the next 
boundary appropriate for its type. For example, the following structure: 



struct { 

unsigned 

char 

short 

} x; 

is mapped out as follows: 



a :3; 

b; 

c; 



Big Endian 
















.ajlilfi 


b 


c 




31 
Li 


28 23 
ttle Endian 




16 













c 


b 




a 




3 


1 

H Padded bits. 




15 




7 


3 





Note that five bits of padding are added after unsigned a so that char b aligns 
on a byte boundary, as required. See Appendix C for more information on big 
and little endian byte ordering. 
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Unions. A union must align on the same boundary as the member with the 
most restrictive boundary requirement. The boundary requirements by increas- 
ing degree of restrictiveness are: byte, halfword, word, and doubleword. For 
example, a union containing char, int, and double data types must align on a a 
doubleword boundary, as required by the double data type. 



Auto* An auto declaration indicates that storage is allocated at execution and 
exists only for the duration of that block activation. 

Static. The compiler allocates storage for a static declaration at compile time. 
This allocation remains fixed for the duration of the program. Static variables 
reside in the program bss section if they are not initialized, otherwise they are 
placed in the data section. 

Register. The compiler allocates variables with the register storage class to 
registers. For programs compiled using the — O (optimize) option, the optimi- 
zation phase of the compiler tries to assign all variables to registers, regardless 
of the storage class specified. 

Extern. The extern storage class indicates that the variable refers to storage 
defined elsewhere in an external data definition. The compiler doesn't allocate 
storage to extern variable declarations; it uses the following logic in defining 
and referencing them: 

Extern is omitted. If an initializer is present, a definition for the symbol is emit- 
ted. Having two or more such definitions among all the files comprising a pro- 
gram results in an error at link time or before. If no initializer is present, a com- 
mon definition is emitted. Any number of common definitions of the same 
identifier may coexist. 

Extern is present The compiler assumes that declaration refers to a name de- 
fined elsewhere. A declaration having an initializer is illegal. If a declared 
identifier is never used, the compiler doesn't issue an external reference to the 
linker. 

Volatile. The volatile storage class is specified for those variables that may be 
modified in ways unknown to the compiler. For example, volatile might be 
specified for an object corresponding to a memory mapped input/output port or 
an object accessed by an asynchronously interrupting function. Except for ex- 
pression evaluation, no phase of the compiler optimizes any of the code dealing 
with volatile objects. 



c 



c 



( 
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NOTE. If a pointer specified as volatile is assigned to another pointer without 
the volatile specification, the compiler treats the other pointer as non-volatile. 
In the following example: 



volatile int *i; 
int * j / 



(volatile*) j = i; 
3108282356*10 



the compiler treats; as a non-volatile pointer and the object it points to as non- 
volatile, and may optimize it. 

The compiler option — volatile causes all objects to be compiled as volatile. 
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Pascal 

Alignment, Size, and Value Ranges 



This section describes how the Pascal compiler implements size, alignment, and 
value ranges for the various data types. 

Table 2.2 shows the value ranges for the Pascal scalar types; Tables 2.3, 2.4, 
and 2.5, which start on the next page, show the size and alignment for the vari- 
ous scalar types. 



ScalarType 


Value Ranges 


boolean 


0or1 


char 


0..127 


integer 


-2 31 2 31 —1 


cardinal 


0..2 32 -1 


real 


See note 1 . 


double 


See note 1 . 



Table 2.2. Pascal Value Ranges. 
NOTE 1: Approximate valid ranges for real and double are: 



real 
double 



Maximum Value 



3.40282356*10" 



38 



1.7976931348623158*10' 



308 



( 



( 





Minimum Values 




Denormalized 


Normalized 


real 
double 


1.40129846*10~ 46 
4. 940 6564584124 654*10^ 324 


1.17549429*10~ 38 
2. 225073 8585072 12 *1Q~ 308 



NOTE 2: Enumerated types with n elements are treated the same as the integer 
subrange 0.,n-4. 



( 
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Unpacked Records 
or Arrays 


Type 


Size 


Alignment 


boolean 


8 


byte 


char 


8 


byte 


integer 


32 


word 


cardinal 


32 


word 


pointer 


32 


word 


file 


32 


word 


real 


32 


word 


double 


64 


doubleword 


subrange of 






0..255 or 
-128..127 


8 


byte 


0..65535 or 
-32768. .32767 


16 


half word 


0..2 32 -1 

rt 31 Q 31 A 


32 


word 


set of char 

set of char 

subrange 


128 


word 


set of a. .b 


see NOTE 


word 


* Variables or fields. 



Table 2.3. Size and Alignment of Pascal Unpacked Records or Arrays (Vari- 
ables or Fields). 

NOTE: The compiler uses the following formula for determining the size of the 
set of a..b: 

size = Lb/32j - La/32j + 1 words 

(The notation Ld indicates the floor of x; i.e., the largest integer not greater than 
x.) 

See the section Rules for Set Sizes at the end of this chapter for rules on speci- 
fying the upper and lower bounds of sets. 
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Packed Arrays 


Scalar Type 


Size 


Alignment 


boolean 


8 


byte 


char 


8 


byte 


integer 


32 


word 


cardinal 


32 


word 


pointer 


32 


word 


file 


32 


word 


real 


32 


word 


double 


64 


doubleword 


subrange of 






0..1 or-1..0 


1 


bit 


0..3. or-2.,1 


2 


2— bit 


0..15 or -8. J 


4 


4-bit 


0..255 or 
-128.. 127 


8 


byte 


0. .65535 or 

-32768.32767 


16 


half word 


—2 31 2 31 —1 


32 


word 


set of char 

set of char 

subrange 


128 


word 


setofa..b 


See NOTE 



( 



( 



Table 2.4. Size and Alignment of Pascal Packed Arrays. 

NOTE: The set of a.h is aligned on an ra-bit boundary where n is computed as 
follows: 

n = | log (size) I 

For example, the set of 0..2 has a size of 3 bits and will align on a 4-bit bound- 
ary, 

(The notation [Yl indicates the ceiling of r, i.e., the smallest integer not less 
than x J 



( 
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The compiler uses the minimum number of bits possible in creating the set of 
a..h field. The following formula is used: 

if b -la/32] *32 + 1 <32then 

size = b -la/32] *32+ 1 bits 
eise 

size - lb/32] -la/32] + 1)*32 bits 

See the section Rules for Set Sizes at the end of this chapter for rules on speci- 
fying the upper and lower bounds of sets. 





Packed Records 


Scalar Type 


Size 


Alignment 


boolean 


1 


bit 


char 


8 


bit 


integer 


32 


word 


cardinal 


32 


word 


pointer 


32 


word 


file 


32 


word 


real 


32 


word 


double 


64 


doubleword 


subrange of 


See Note. 


bit/word* 



Table 2.5. Size and Alignment of Pascal Packed Records. 

NOTE: The compiler uses the minimum number of bits possible in creating a 
subrange field in a packed record. For the subrange of a..b\ 

If a>0 then size = \ log (bf 1)\ bits 

If a<0 then size = max(\ log (b-k1) I J log ( -al\ ) + 1 bits 

To avoid crossing a word boundary, the compiler moves data types aligned to 
bit boundaries in a packed record, to the next word. 



Pascal Arrays, Records and Variant Records 



Arrays. Arrays have the same boundary requirements as the data type specified 
for element of the array. The size of an array is the size of the data type multi- 
plied by the number of elements. For example, for the following declaration: 

x : array [ 1 . . 2 , 1 . . 3 ] of double ; 

the size of the resulting array is 48 bytes (2*3*8, where 8 is the size of the dou- 
ble floating point type in bytes). 
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Records. Each member of a record begins at an offset from the structure base. 
The offset corresponds to the order in which a member is declared; the first 
member is at offset 0. 

The size of a record in the object file is the size of its combined members plus 
padding added, where necessary, by the compiler. The following rules apply to 
records: 

• Records must align on the same boundary as that required by 
the member with the most restrictive boundary requirement. 
The boundary requirements by degree of restrictiveness are: 
byte, halfword, word, and doubleword, with doubleword being 
the most restrictive. 

® The compiler terminates the record on the same alignment 
boundary on which it begins. For example, if a record begins 
on an even-byte boundary, it also ends on an even-byte bound- 
ary (i.e., the size is a multiple of the alignment). 

For example, the following structure: 

type S^record 

V; integer 

n:array [1. .10] of char 
end; 

is mapped out in storage as follows: 



( 



Big Endian 




V 


V 


V 


V 


nO 


n1 


n2 


n3 




Byte 


12 3 4 5 6 7 






n4 


n5 


n6 


n7 


n8 


n9 


iliili 


lllll 




Byte 
Little Em 


8 9 10 11 12 13 14 15 
clian 






fill 


liS 


n9 


n8 


n7 


n6 


n5 


n4 




Byte 


15 14 13 12 11 10 9 I 


3 


Qwf/t 


n3 


n2 


n1 


nO 


V 


Vi 


Vi 


v 3 




Byte 
H Pad< 


7 6 5 4 3 2 10 
ted bytes 





See Appendix C for more information on big and little endian byte ordering. 

Note that the length of the structure is 16 bytes, even though the byte count as 
defined by the v .integer and the n:array[L.10] of char components is only 14. 
Because integer has a stricter boundary requirement (word boundary) than char 
(byte boundary), the structure must end on a word boundary (a byte offset divis- 



c 



( 
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ible by four). The compiler therefore adds two bytes of padding to meet this 
requirement. 

An array of data structures illustrates the reason for this requirement. For ex- 
ample, if the above structure were the element-type of an array, some of the 
vUnteger components wouldn't be aligned properly without the two-byte pad. 

Alignment requirements may cause padding to appear in the middle of a struc- 
ture. For example, by rearranging the structure in the last example to the fol- 
lowing: 

type S=record 

niarray [1..10] of char; 

v: integer 
end; 

the compiler maps the structures as follows: 



Big Endian 





nO 


n1 


n2 


n3 


n4 


n5 


n6 


n7 


Byte 


12 3 4 


5 6 7 




n8 


n 9 illlfllll v 


V 


i 

V j V 



Byte 8 9 10 11 ■ 12 13 14 15 



Little Endian 



Byte 



Byte 



V 


V 


V 


V 


IIIIIUI n9 


n8 


15 V 


I 13 12 11 10 S 


8 


n7 


n6 


n5 


n4 


n3 


n2 


n1 


nO 



7 6 5 4 3 2 10 



M Padded bytes 



Note that the size of the structure remains 16 bytes, but two bytes of padding 
follow the n component to align v on a word boundary. 
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Ranges in a packed record are packed from the most significant bit to least si£ 
nificant bit in a word. The following packed record: 

type virtual_address=packed record 

offset : 

page : 

segment : 

supervisor : 
end; 

is mapped out as follows: 



0. .4095; (* 12 bits *) 

0. .1023; (* lObits *) 

0. .511; (* 9 bits *) 

0..1; (*lbit*) 



C 



Big Endian 

Byte 



offset 



Bit 31 



Little Endian 



Byte 1 



page 



segment 



9 14 

supervisor 





segment 


page 


offset 



Bit f30 
supervisor 



22 



12 



c 



I 



See Appendix C for more information on big and little endian byte ordering. 

Ranges in an unpacked record are packed from the most significant bit to the 
least significant bit but each range is aligned to the appropriate boundary as in- 
dicated in table 2.4 The following unpacked record: 



type virtual_address = record 

offset: 0, 

page : . 

segment : . 

supervisor; 0. 

end; 

is mapped out as follows (big-endian): 



,4095; (* 12 bits *) 
,1023; (* 10 bits *) 
,511; (*9bits*) 
,1; (*lbit*) 



Bit 31 



offset 



page 



19 15 



Bit 63 54 

II Padded bits 



I5f 14 

supervisor 



segment 



32 
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For unpacked records, the compiler aligns a non-range element that follows a 
range declaration to the next boundary appropriate for its type. For example, 
the following structure: 

var x: record 

a:0..7; (* 3 bits packed *) 

b: char; (* 8 bits *) 

c: -32768. .32767/ (* 16 bits *) 
end; 



is mapped out as follows: 



B 


ig Endian 

















a 




b 


c 


31 28 23 
Little Endian 




16 










c 




b 


111 


•ll'lii 


a 


3 


1 

B Padded bits 




15 




7 


3 



Note that five bits of padding are added after a so that b aligns on a byte bound- 
ary, as required. (See Appendix C for more information on big and little en- 
dian byte ordering.) 

Variant Records. A variant record must align on the same boundary as the 
member with the most restrictive boundary requirement. The boundary require- 
ments by increasing degree of restrictiveness are: byte, halfword, word, and 
doubleword. For example, a variant record containing char, integer, and dou- 
ble data types must align on a a doubleword boundary, as required by the dou- 
ble data type. 
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For a packed record, booleans, chars, and ranges are bit-aligned, and all other 
types are word or double-word aligned as is appropriate for the type (see table 
2.4). 

The previous record done as a packed record: 

var x: packed record 

a: 0. .7; (*3bits *) 

b: char; (*. 3 bits *), 

c: -32768, .32767; (* 16 bits*) 
end; 



c 



is mapped out as follows: 



Big Endian 



31 28 20 

Little Endian 



31 27 
H Padded bite. 



zu 



WTO:* 









11 



3 



c 
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The maximum number of elements permitted in a set ranges between 481 and 
512. This variance is due to the way Pascal implements sets. For efficient ac- 
cessing of set elements, Pascal expects the lower-bound of a set to be a multiple 
of 32. If for the set specified: 

set of a..b 

a is not a multiple of 32, Pascal "adds" elements to the set from a down to the 
next multiple of 32 less than a. For example, the set: 

set of 5 . .31 

would have internal padding elements 0..4 added. These padding elements are 
inaccessible to the program. This implementation sacrifices some space for a 
fast, consistent method of accessing set elements. 

the padding requried to pad the lower bound down to a multiple of 32 varies 
between and 31 elements. 

For the set of a.b to be a valid set in Pascal, the following condition must be 
met: 



size* 



:(b-32La/32j+l)<512 



The table below shows some example sets and whether they are valid by the 
above equation. 



Specification 


Lower 


Upper 


Set size 


Valid Size 


set of 1. .511 


0* 


511 


512 


Yes 


set of 0. .511 





511 


512 


Yes 


set of 1. .512 


0* 


512 


513 


No 


set of 31. .512 


0* 


512 


513 


No 


set of 32. .512 


32 


512 


481 


Yes 


set of 32. .543 


32 


543 


512 


Yes 


*As padded down to by Pascal. 
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3 
Language Interfaces 



This chapter describes the coding interfaces between C and Pascal; it gives rules 
and examples for calling and passing arguments among these languages. 

You may need to refer to Chapter 2 for detailed information on how the vari- 
ables of the various languages appear in storage. For information on interfaces 
between FORTRAN programs and programs written in C or Pascal, refer to the 
Part I of the FORTRAN Programmer's Guide and Language Reference manual. 

Pascal/C Interface 

General Considerations 

In general, calling C from Pascal and Pascal from C is fairly simple. Most data 
types have natural counterparts in the other language. However, differences do 
exist in the following areas: 

• single-precision floating point, procedure, and function parame- 
ters 

• Pascal by-value arrays 

• file variables 

• passing string data between C and Pascal 

• passing variable arguments 

These differences are discussed in the following sections. 

Single-precision floating point. In function calls, C automatically converts 
single-precision floating point values to double precision, whereas Pascal passes 
single-precision floating by-value arguments directly. Follow these guidelines 
when you wish to pass double-precision values between C and Pascal routines: 

• If possible, write the Pascal routine so that it receives and re- 
turns double-precision values, or 

• If the Pascal routine cannot receive a double-precision value, 
write a Pascal routine to accept double-precision values from C, 
then have that routine call the single-precision Pascal routine. 

There is no problem passing single-precision values by reference between C 
and Pascal. 

Procedure and function parameters. C function variables and parameters 
consist of a single pointer to machine code, whereas Pascal procedure and func- 
tion parameters consist of a pointer to machine code, and a pointer to the stack 
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frame of the lexical parent of the function. Such values can be declared as 
structures in C. To create such a structure, put the C function pointer in the first 
word, and in the second. C functions cannot be nested, and thus have no lexi- 
cal parent; therefore, the second word is irrelevant. 

You cannot call a C routine with a function parameter from Pascal. 

Pascal by-value arrays. C never passes arrays by value. In C, an array is ac- 
tually a sort of pointer, and so passing an array actually passes its address, 
which corresponds to Pascal by-reference (VAR) array passing. In practice this 
is not a serious problem because passing Pascal arrays by value is not very effi- 
cient, and so most Pascal array parameters are VAR anyway. When it is neces- 
sary to call a Pascal routine with a by-value array parameter from C, pass a C 
structure containing the corresponding array declaration. 

File variables. The Pascal text type and the C stdio package's FILE* are com- 
patible. However, Pascal passes file variables only by reference; a Pascal rou- 
tine cannot pass a file variable by value to a C routine. C routines that pass 
files to Pascal routines should pass the address of the FILE* variable, as with 
any reference parameter. 

Strings. C and Pascal programs handle strings differently. In Pascal, a string is 
defined to be a packed array of characters, where the lower bound of the array 
is 1, and the upper bound is some integer greater than 1. For example: 

var s: packed array [1 . .100] of char; 

where the upperbound (100 in this case) is large enough to efficiently handle 
most processing requirements. This differs from the C style of indexing arrays 
from to MAX-1. In passing an array, Pascal passes the entire array as speci- 
fied, padding to the end of the array with spaces. 

Most C programs treat strings as pointers to a single character and use pointer 
arithmetic to step through the string. A null character (\0 in C) terminates a 
string in C; therefore, when passing a string from Pascal to C, always terminate 
the string with a null character (chr(0) in Pascal). 



( 
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The following example shows a Pascal routine that calls the C routine atoi and 
passes the string s. Note that the routine ensures that the string terminates with 
a null character. 



type 

astrindex = 1 . . 20; 

astring = packed array [astrindex] of char; 

function atoi (var c: astring): integer; external; 

program ptest (output) ; 
var 

s: astring; 
i: astrindex; 
begin 
argv(l f s) ; { This predefined Pascal function 

is a MIPS extension } 
writeln (output, s) ; 

{ Guarantee that the string is null-terminated 
(but may bash the last character if the argument 
is too long) . "lbound" and "hbound" are MIPS 
extensions. } 
s[hbound(s)] := chr(0) 
for i := lbound (s) to 
if s[i] = ' r then 
begin 

s[i] := chr(0 
break; 
end; 
writeln (output, atoi(s)); 
end. 



(s) do 




hecks for null 
character. 



For more information on atoi, see the atof(3) (for BSD) or strtol(3c) (for Sys- 
tem V) man page in the UNIX Programmer's Manual. See Figure 3.3 for an- 
other example of passing strings between C and Pascal. 

Variable number of arguments- C functions can be defined that take a vari- 
able number of arguments (printfmd its variants are examples). Such functions 
cannot be called from Pascal 

Type checking. Pascal checks certain variables for errors at execution time, 
whereas C doesn't. For example, in a Pascal program, when a reference to an 
array exceeds its bounds, the error is flagged (if runtime checks aren't sup- 
pressed). You could not expect a C program to detect similar errors when you 
pass data to it from a Pascal program. 
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One main routine. Only one main routine is allowed per program. The main 
routine can be written either in Pascal or C. Here are examples of C and Pascal 
main routines: 



c 



Pascal 


C 


program p (input f output) ; 
begin 

writeln("hi!") ; 
end. 


main ( ) { 

print f ("hi\n!") ; 
} 



Calling Pascal from C 



To call a Pascal function from C, write a C extern declaration to describe the 
return value type of the Pascal routine; then write the call with the return value 
type and argument types as required by the Pascal routine. See Figure 3.1 for 
an example. 

C return values. Table 3.1 below serves as a guide to declaring the return 
value type. 



If Pascal function returns: 


Declare C function as: 


integer 


int 


cardinal 


unsigned int 


char 


char 


boolean 


char 


enumeration 


unsigned, or corresponding enum 




enum (C's enum are signed) 


real 


none 


double 


double 


pointer type 


corresponding pointer type 


record type 


corresponding structure or 




union type 


array type 


corresponding array type 


1 Applies also to subranges with lowers bound <0. 


2 Applies also to subranges with lower bounds >=0. 



Table 3.1. Declaration of Return Value Types. 

To call a Pascal procedure from C 5 write a C extern declaration of the form 

extern void name () ; 

and then call it with actual arguments with appropriate types. Table 3.2 serves 
as a guide for what values to pass corresponding to the Pascal declarations. C 
does not permit declaration of the formal parameter types, but instead infers 
them from the types of the actual arguments passed. See Figure 3,2 for an ex- 
ample. 

C to Pascal arguments. Table 3.2 shows the C argument types to declare in 
order to match those expected by the called Pascal routine. 



c 



( 
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If Pascal expects: 


C argument should be: 


integer 


integer or char value -2 31 ..2 31 - 1 


cardinal 


integer or char value 0..2 32 -1 


subrange 


integer or char value in subrange 


char 


integer or char (0.. 255) 


boolean 


integer or char (0 or 1 only) 


enumeration 


integer or char (0..N-1) 


real 


none 


double 


float or double 


procedure 


struct {void *p(); int *l} 


function 


struct {function-type *f(); int *l} 


pointer types 1 


pointer type 

und <0. := Ibound(s) 


reference 
parameter 


pointer to the appropriate type 


record types 


structure or union type 


by-reference 
array parameters 


corresponding array type 


by-reference text 


FILE** 


by-value 

array parameters 


structure containing the corresponding 
array 


1 See note below. 





Table 32, Pascal to C Data Types. 

NOTE: To pass a pointer to a function in a call from C to Pascal, you must 
pass a structure by value; the first word of the structure must contain the func- 
tion pointer and the second word a zero. Pascal requires this format because it 
expects an environment specification in the second word. 
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Example: Calling a Pascal function. Figure 3.1 shows an example of a C 
routine calling a Pascal function. 



( 



Pascal routine 

function bah ( 
var f: text; 
i : integer 
) : double; 
begin 

end {bah}; 

C declaration of hah 

extern double bah(); 

Ccall 

int i; double d; 

FILE *f; 

d = bah(&f r i) ; 



Figure 3 J. Calling a Pascal Function from C. 

Example: Calling a Pascal procedure. Figure 3.2 shows an example of a C 
routine calling a Pascal procedure. 



Pascal routine 

type 

int_array = array [1 . , 100] of integer; 
procedure zero ( 

var a: int_array; 

n: integer 

) : integer; 
. begin 

end {zero}; 

C declaration 

extern void zero ( ) ; 

C call 

int a [100] ; int n; 
zero (a f n) ; 



( 



Figure 32. Calling a Pascal Procedure from C. 
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Example: Passing strings to a Pascal procedure. Figure 3.3 is an example of 
a C routine that passes strings to a Pascal procedure, which then prints them; the 
example illustrates two points: 



The Pascal routine must check for the null [chr(O)] character, 
which indicates the end of the string passed by the C routine. 

The Pascal routine must not write to output, but instead uses the 
stdout file-stream descriptor passed by the C routine. 



C routine 

/* Send the last command-line argument 
to the Pascal routine */ 

♦include <stdio.h> 
main (argc, argv) 

int argc; char **argv; 

{ 

FILE *temp = stdout; 

if (argc != 0) 

p__routine (&tefflfc>, argv[argc - 1]); 



} 



Pascal routine 

{ We assume the striftg passed to us by 

will not exceed 10 0\ bytes in length 
type 

astring = packed arrky [1 . . 100] of 
procedure p__routine (va^ f : text; var c 
var 

i: integers- 
begin 

i := lbound(c) ; 
while (i < hbound(c)) 

begin 

write (£, c[i]) 

i := i + 1; 

end; 
writeln (f ) ; 
end; 



Checks for null 
character. 



the C program 



char; 
astring) ; 



aAd (c[i] <> chr(O)) do 



Writes to file-stream 
descriptor passed by C. 



Figure 3.3. Passing Strings to a Pascal Procedure from C. 



Calling C from Pascal 



Pascal to C arguments. To call a C routine from Pascal, write a Pascal decla- 
ration describing the C routine. Write a procedure declaration or, if the C rou- 
tine returns a value, a function declaration. Write parameter and return value 
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declarations corresponding to the C parameter types, using the table below as a 
guide. 



( 



If C expects: 



int 1 

unsigned inf 

short 3 

unsigned short 

char 4 

signed char 

float 

double 

enum type 

string (char *) 

pointer to function 

FILE* 

FILE ** 

pointer type 

struct type 
union type 
array type 



Pascal parameter should be: 



integer 
cardinal 

integer (or -32768. .32767) 
cardinal (or 0..65535) 
char 

integer (or -128. .127) 
double 
double 

corresponding enumeration type 
packed character array passed by reference (VAR) 
none 
none 

text, passed by reference (VAR) 
corresponding pointer type 
or corresponding type passed by reference (VAR) 
corresponding record type 
corresponding record type 
corresponding array type passed by reference 



1 Same as types signed int, long, signed long, signed 
2 Same as types unsigned, unsigned long 
3 Same as type signed short 
4 Same as type unsigned char 



c 



Table 33. Pascal Parameter Data Type Expected by C: 

Note: A Pascal routine cannot pass a function pointer to a C routine. 



( 
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Example: Calling a C procedure. Figure 3.4 shows an example of calling a 
C procedure from Pascal. 



C routine: 

void bah (i, f , s) 

int i ; 

float f; 

char *s; 
{ 

} 

Pascal declaration: 

procedure bah ( 
i: integer; 
f: double; 

var s: packed array [1 .. 100] of char) 
external; 

Pascal call: 

str := "abc\0"; 
bah(i, 1.0, str) 



Figure 3.4. Calling a C Procedure from Pascal. 

Example: Calling a C function* Figure 3.5 shows an example of calling a C 
function from Pascal. 



C routine: 

float humbug (f, x) 

FILE **f; 

struct scrooge *x; 
{ 



} 



Pascal declaration: 

type 

scrooge_jptr = A scrooge; 
function humbug ( 
var f: text; 
x: scrooge_ptr 
) : double; 
external; 

Pascal call: 

x := humbug ( input , sp) ; 



Figure 3.5. Calling a C Function from Pascal. 
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Example: Passing arrays. Figure 3,6 shows an example of calling a C func- 
tion from Pascal 



c 



C routine: 

int sum (a, n) 

int a [ ] ; 

unsigned n; 
{ 

} 

Pascal declaration: 

type 

int__array = array [0 ., 100] of integer; 
function sum ( 

var a: int_array; 
n: cardinal 
) : integer; 
external; 
avg := sum ( samples , hbound( samples) +1) / 
(hbound (samples) +1) ; 



Figure 3.6. Passing Arrays Between Pascal and C. 



c 



3-10 



Languages Programmer's Guide 



Improving Program 
Performance 



Introduction 



Profiling 



Overview 



This chapter describes facilities that can help reduce the execution time of your 
programs; it contains the following major sections: 

• Profiling, which describes the advantages of the profiler and 
how to use it. The profiler isolates those portions of your code 
where execution is concentrated and provides reports that indi- 
cate where you should devote your time and effort for coding 
improvements. 

• Optimization, which describes the compiler optimization facility 
and how to use it. The section also gives examples showing 
optimization techniques. 

• Limiting the Size of Global Data Area, which describes the 
global data area and how, through controlling the size of vari- 
ables and constants that the compiler places in this area, you 
can improve program performance. 



The best way to produce efficient code is to follow good programming prac- 
tices: 

• Choose good algorithms and leave the details to the compiler. 

• Avoid tailoring your work for any particular release or quirk of 
the compiler system. 

As technological advances cause MIPS to make changes to the current compiler 
system, anything you tailor now might negatively affect future program per- 
formance. Moreover, tailored code might not work at all with new versions of 
the system. To take action on possible compiler inefficiencies, report them di- 
rectly to MIPS. 



This section describes the concept of profiling, its advantages and disadvan- 
tages, and how to use the profiler. 

Profiling helps you find the areas of code where most of the execution time is 
spent. In the typical program, execution time is confined to a relatively few 
sections of code; it's profitable to concentrate on improving coding efficiency in 
only those sections. The compiler system provides the following profile infor- 
mation: 



Languages Programmer's Guide 



4-1 



Chapter 4 



• pc sampling (pc stands for program counter), which highlights ^ 
the execution time spent in various parts of the program. f 

You obtain pc sampling information by link editing the desired 
source modules using the ~p option and then executing the re- 
sulting program object, which generates profile data in raw for- 
mat. 

• invocation counting, which gives the number of times each pro- 
cedure in the program is invoked. 

• basic block counting, which measures the execution of basic 
blocks (a basic block is a sequence of instructions that is en- 
tered only at the beginning and which exits only at the end). 
This option provides statistics on individual lines. 

You obtain invocation counting and basic block counting infor- 
mation using the pixie program. Pixie takes your source pro- 
gram and creates an equivalent program containing additional 
code that counts the execution of each basic block. Executing 
pixie and the equivalent program generate the profile data in 
raw format. 

Using the prof program, you can created a formatted listing of the raw profile 

data. The listings can indicate where to correct sub-optimal coding, substitute 

better algorithms, or substitute assembly language. The listings also indicate if i 

your program has exercised all portions of the code. ^ 

Figure 4.1 gives an example of a pc sampling listing produced from a program 
compiled with the -p compiler option. The prof program produced the listing 
from the raw profile data using the -procedure option. 



c 
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Procedures — PC Sampling 
Profiler option: —procedure 






j. — . T . * 



fttttttttttttttttttttttttttt'tttt 



hcch mxtypl® >t^^vc 8,00= 5>yt^{^) £ok ^<2$ o£ $<£§11 iPllHill 



lllgllll; 



i^i^iSi^^^^^^^^^^^^^^^^^f^i^^^lJP^Il 




&♦ 10 v^it«js-t^i«L9 (, ,/t^«t output, -c^ 
0^16 write_integer ( . . /texfoutput .c) 
w ri tre In f < < / %&y& ® » t pxji ^ ) 

||p| |||j i||li||l 



.03 seconds (12.5% of execution time)) 
was spent in writejtateger. 



.16 seconds (66.7% of total executio | 
time) were spent cumatively in the | 
main, writejstring, write_char, and 
write_integer routines. 



The name of the source 
file for write__integer is 
../textoutput.c. 



Figure 4.1. Profiler Listing for PC Sampling 



Figures 4.2 through 4.6 shows listings from raw data produced by pixie. The 
prof option used is given at the top of each figure. 
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Procedures — Invocation Counting 
Profiler option:— pixie -invocation 



c 



-invocations] using basic-block counts; 

the called procedures are sorted in descending order by number of 

calls; a r l f in the columns marked '#calls f or 'line' means that data 

is unavailable because part of the program was compiled without 

profiling. 



called procedure #calls %calls from line, calling procedure (file) 



4017 81.51 



write char 



' 453 

428 

30 

4014 

453 

442 

L. 




81 
9 
9 
n 



eoln was called 4017 times from. 
line 37 of main This presented 81 J51^ 
of t h e ca! is to eo [n . " " 



write_string 



write_integer 
eof 

writeln 

readln 
sbrk 



close 
fflush 









453 

453 

453 

453 

30 



453 

453 

453 

30 

1 

1 

453 

30 

1 

453 

30 

4 

1 

1 

4 

4 











24 

24 

24 

24 

1 



50 

50 

93 

6 





93 

6 



93 

6 

66 

16 

16 

100 

100 





.69 
.61 
.75 
.23 
.00 
.02 
.37 
.63 
.40 
.60 
.00 
.00 
.00 
.59 
.59 
.59 
,59 
.63 
.00 
.00 
.00 
.40 
.19 
.21 
.21 
.60 
.20 
.21 
.79 
.21 
.67 
.67 
.67 
.00 
.00 
.00 




19 
17 
43 
45 
42 
•43L 



main 
main 
main 
main 
main 



ix . | 
ix.p) 
pix.p) 
pix.p) 
pix.p) 
pix.p) 
pix.p) 



The source code for mam tej 
th$ fild pix.p- 

■""i&U' 



225 

257 

284 

286 

31 

29 

31 

31 

23 

189 

31 

31 

45 

23 

28 

14 

29 

23 

47 

39 

21 

207 

110 

115 

108 

107 

49 



write_integer ( 
write cardinal 



. /textoutput 
. . /textoutpu 
( . . /textoutp 



write 
write 
main 
main 
main 
main 
main 
write 
main 
main 
main 
main 
main 
main 
main 
main 
main 
main 
main 
morecore 
malloc ( 
malloc ( 
fclose ( 
fclose ( 
filbuf 



_real 

__real 

(pix.p 

(pix 

(pix 

(pix 

(pix 

_enum 

(pix.p 

(pix.p 

(pix.p 

(pix.p 

(pix 

(pix 

(pix 

(pix 

(pix 

(pix 

(pix 



. /textoutput . 
. /textoutput , 



.c) 

c) 
at .c) 
) 
) 



( 



/textoutput . c 



( . . /malloc. c) 
. /malloc .c) 
. /malloc .c) 
./flsbuf .c) 
. /flsbuf .c) 
. ./filbuf .c) 



Figure 4.2. Profiler Listing for Procedure Invocations. 



( 
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Procedures — Basic Block Counts 
Profiler option :-pixied -procedures 



-p [rocedures] using basic-block counts; 

sorted in descending order by the number of cycles executed in each 

procedure; unexecuted procedures are excluded 



]4£137751 cycles^ ^ 

cycles %cycles cum % 



Total number of program cycles 




42 



cycles 
/call 

34 
443503 
30 
23 
62 
133 

*23- 



bytes procedure 
/line 



(file) 



Cumulative total, i.e., 92.91% 

of all cycles used by wrffe jchar, 
main, eoln, and read_charr 



Cycles USed by write^char. 

in units and as a percentage 



TD3™" 

90 

82 

55 

35 

15 

13 

11 

6 

5 

5 



U.U U 1 U U.0U 

0.00 100.00 

0.00 100.00 

0.00 100.00 

0.00 100.00 



60 

6 

6 

368 

58 

15 



3%^ &rite cha r ( . . /textoutpujt^cj, 

2 6 main (Tixfont^ tT 

44 eoln ( . ./texti nput .c) 

27 read_char ( . . / :extinput . c) 

8 write_chars ( . . /textoutput . c) 
14 write_integer (.. /textoutput .c) 
T X£ TJ write_string (.. /textoutput . c) 
readln ( . . /tex linput .c) 
writeln ( . . /te Ktoutput .c) 

of ( . . /textir put .c) 
_flsbuf (. ./flsbuf .c) 
13 _^lll.,/,i.,../r^.i,.l,l.,,r.\.,, 
6 wri 
6 rea 
11 mor 
10 mal 



;:§fatj$^ 

wite^char compiled from 

source file textoutpuLc 



9 pad (.. /textoutput .c) 
1"5 ieyeis^C. ./reset .c) 
13 f openjy. /fopen.c) 



Q§ 2_ 13 f open jj. / 

^""**"*""' i ^sbrk ( . . / sbrk . s ) 



0.00 100.00 



11 

35 
5 



00 100.00 

00 100.00 

00 100.00 

00 100.00 

00 100.00 



15 rewrite (,, /rewrite .c) 
5 fstat (. ,/fstat.s) 



fopen used 
per calf and 



4lhraSjr^ 

13 bytes per line. 



fc) 



l.s) 



5 creat ( . . /stringargl . s) 



Figure 4.3. Profiler Listing for Procedures Based on Basic Blocks Counts. 



Languages Programmer's Guide 



4-5 



Chapter 4 



Procedures — Basic Block Counts (with clock time) 
Profiler option:— pixie— procedure —clock 



-p [rocedures] using basic-block counts; 

sorted in descending order by the number of cycles executed in each 

procedure; unexecuted procedures are excluded 




148137751 cyclesVU-8.5172 seconds at 8.00 megahertz 



cycles %cycles cum % seconds 



48071708 


32 


45 


32. 


45/ 


6 


0090 


42443503 


28 


65 


61. 


If 


5 


3054 


26457936 


17 


86 


78. 


9f6 


3 


3072 


20662326 


13 


95 


92. 


r 1 


2 


5828 


4307932 


2 


91 


95. 


B2 





5385 


3678408 


2 


48 


98. 


30 





4598 


1573858 


1 


06 


99. 


36 





1967 


362700 





24 


99. 


61 





0453 


279002 





19 


99. 


B0 





0349 


251152 





17 


99. 


T 





.0314 


30283 





02 


99. 


919 





.0038 


13.3 91 





.01 


100. 


°\ 





.0017 


2923 





.00 


100. 


oo\ 


V ° 


.0004 


1356 





.00 


100. 


00 




.000^ 


735 





.00 


100. 


00 







El 


116 





.00 


100. 


00 





.00 


DO 


105 





.00 


100. 


00 





■ 0C 


30 


90 





.00 


100. 


00 





.00 


DO 



bytes procedure 
line 



(file) 



The profiler computes the time in 
seconds based on the megahertz 

machine speed specified in the 
—clock option. 



c) 



1 3 j ''*""' 14 wr 1 1 e_int ege r ' '('.'./ 1 ext out pu t . c) 

29 16 write_string (.. /textoutput .c) 

26 67 readln (.. /text input .c) 

20 30 writeln (., /textoutput .c) 

19 44 eof (. ./text input. c) 

63 11 _flsbuf (. ./flsbuf .c) 

60 13 _refill (.. /refill .c) 

6 6 write (. ."/write, s) 

6 6 read (../read.s) 

368 11 morecore ( . . /malloc. c) 

58 10 malloc (.. /malloc. c) 
pad (.. /textoutput . c) 



This listing contains the same Information 
as the listing shown In, Figure 4-3, except 
that this listing also contains the number 
of seconds spent in each procedure. 



6 0.0 
5 0.0 
5 0,00 100.00 



3 loo.oo o.oooo 

- 100.00 0.0000 
0.0000 



*TT 



9 

15 reset ( 

13 fopen ( 

5 sbrk (. 

15 rewrite 

5 fstat ( 

isatty 

gtty (. 



12 

11 

5 

5 

5 



. . /reset .c) 
. . /fopen.c) 
. /sbrk'. s) 

( . . /rewrite .c) 
. . /fstat .s) 
( . , /isatty .c) 
./gtty.c) 
ioctl (.. /simple . s) 
open ( . . /stringargl . s) 
creat (.. /stringargl . s) 



( 



( 



Figure 4.4. Profiler Listing for Procedures Based on Basic Blocks Counts (with clock times). 



{ 
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Heavy — Basic Block Counts 
Profiler option: —pixie —heavy 



-h[eavy] using basic-block counts; 

sorted in descending order by the number of cycles executed in each 

line; unexecuted lines are excluded 



prnr.p.dnrp (f i 1 &) 




. /textoutput .c) 



main (fixfont.p) 
read_char (.. /tejct input .c) 
main (fixfont.p) 



The most heavily used line 
is 120, located in procedure 
writejshar, compiled from 
source file textoutput c. 



write_char {.. /textoutput .c) 
write_char (.. /textoutput .c) 
eoln ( . . /text input .c) . 
read_char (.. /text input .c) 
main (fixfont.p) 
write_chars (. ./textoutput .c) 
write_char (.. /textoutput .c) 
write_char (.. /textoutput .c) 
write_integer (.. /textoutput T c) 
main (fixfont.p) 
write^integer (. ./textoutput .c) 
main (fixfont.p) 
eoln (. ./text input .c) 
main (fixfont.p) 
main (fixfont.p) 
write_string (.. /textoutput .c) 
write_chars (.. /textoutput .c) 
write_chars (.. /textoutput .c) 
write_chars (.. /textoutput .c) 
write_chars (.. /textoutput . c) 
main (fixfont.p) 



line bytes 



cycles 



cum % 




foMUl. 



Lines 120, 31, and 

of total program 
cycles. 



47 

106 

112 

197 

45 

198 

39 

28 

36 

37 

150 

48 

47 

49 

18 

31 



36936 
i / y b / z 4 
1795872 



TT 
4 
16 
32 
3F! 
2 
1 



17 
14 
14 
13 



UJo^l 1.15 

13945 0.95 

13945 0.95 

64294 0.92 



1.85 84.88 
-T721 6-6t=Oc 

1.21 J7.3X 
88.45 
89.41 
90.36 
91.28 



: Line 38 of lextoutputc has 8 
bytes of code, used 1,795,872 
cycles, or 1.21% of total 
program cycles. * 



44 

4 

4 

28 

20 

100 



571050 0.39 95.46 

567855 0.38 95.84 

567855 0.38 96.22 

487387 0.33 96.55 

348150 0.24 96.79 



348000 



0.23 97.02 



Figure 4.5. Profiler Listing for Heavy Line Usage. 
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Lines — Basic Block Counts 
Profiler option: —pixie —lines 



-l[ines] using basic-block counts; 

grouped by procedure, sorted by cycles executed per procedure; 

'?' means that because a procedure was compiled without profiling, 

we lack line number information for it 



p r ocejsUHf^^tTTTeT 

write_char ( . . /textoutput .c) 




line bytes 



cycles %cycles 



The statistics to the right describe 
\\ms of code in prooedum witejshar 
compiled from the source fife textout* 
putc. 



main (fixfont.p) 



iliiiilliiiliilliiiiiiii 



eoln ( . . /textinput .c) 
read_char ( . . /t 



28 l^of^no^B 



write_chars (.. /textoutput .c) 




31 


116 


58 


8 


59 


56 


60 


28 


61 


16 


18 


20 


19 


8 


25 


12 


28 


4 



c 



( 



Figure 4.6. Profiler Listing for Line Information. 
How Basic Block Counting Works 

Figure 4.7 on the next pages gives the steps to follow in obtaining basic block 
counts. Details of the steps shown in the figure are as follows: 

1. Compile and link-edit Do not use the — p option. For ex- 
ample; 

cc -c myprog.c 

cc -o myprog myprog . o 

2. Run the profiling program pixie. For example: 

pixie -o myprog . pixie myprog 

Pixie takes myprog and writes an equivalent program con- 
taining additional code that counts the execution of each 



( 
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basic block. Pixie also generates a file QnyprogAddrs) that 
contains the address of each of the basic blocks. For more 
information, see the pixie(l) section in the User's Reference 
Manual 

3. Execute myprog.pixie, which was generated by pixie. For 
example: 

myprog.pixie 

This program generates the file myprog.Counts, which con- 
tains the basic block counts. 

4. Run the profile formatting program prof, which extracts 
information from myprogAddrs and myprog.Counts, and 
prints it in an easily readable format. For example: 

prof -pixie myprog myprog.Addrs myprog.Counts 

NOTE: Specifying myprog.Addrs and myprog.Counts is 
optional; pixie searches by default for with names in having 
the format 
program jiame Addrs and program jtame.Counts. 

You can run the program several times, altering the input 
data, and create multiple profile data files, if you desire. 
See the section Averaging Prof Results later in this chapter 
for an example. 

You can include or exclude information on specific procedures within your 
program by using the — only or — exclude prof options (Table 4.1). 
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Stepl 



Step 2 



Step 3 



Step 4 



Compile and link. 



Execute pixie 



prog ram. Add rs 



Execute 
program.pixie 



Execute prof 



prof option; 
-pixie 





prof options: 
pixie -feedback 



For the programmer 



A formatted listing 
of profile statistics. 



Fortheoprnpiter 

A feedback file used by the driver -cord 
option in maximizing cache efficiency. 
See Reducing Cache Conflicts in this 
chapter for more information. 



c 



( 



Figure 47. How Basic Block Counting Works. 



Averaging Prof Results 



A single run of a program may not produce the typical results you require. You 
can repeatedly run the version of your program created by pixie, varying the 
input with each run,; then, you can then use the resulting .Counts files to pro- 
duce a consolidated report. For example: 

1. Compile and link-edit. Do not use the — p option. For exam- 
ple: 



( 
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cc -c myprog. c 

cc -o myprog myprog . o 

2. Run the profiling program pixie. For example: 

pixie -o myprog. pixie myprog 

This step produces the myprog Addrs file to be used in Step 4, 
as well as the modified program myprog.pixie. 

3. Run the profiled program as many times as desired. Each time 
you run the program, a myprog.Counts file is created; rename 
this file before executing the next sample run. For example: 

myprog. pixie < input 1 > outputl 
mv myprog . Counts myprogl . Counts 
myprog. pixie < input 2 > output 2 
mv myprog . Counts myprog2 . Counts 
myprog. pixie < input 3 > output 3 
mv myprog . Counts myprog3 . Counts 

4. Create the report as shown below. 

prof -pixie myprog myprog. Addrs myprog [123] .Counts 

prof takes an average of the basic block data in the 
myprogl. Counts, myprogl. Counts, and myprog3. Counts files to 
produce the profile report. 
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How PC-Sampling Works 

Figure 4,8 gives the steps to follow in obtaining pc sampling information. 



Compiler 
— p option. 



Step 1 



Compile and link. 



Step 2 



Step 3 



Execute program 
(collect data) 



prof format 
option (s) 



^r 



Run prof 
(format data) 



Y 

For the programmer 

A formatted listing 
of profile statistics. 



J^ 7 



Profile Data File 
(mpn.out) 



For the compiler 



A feedback file used by the driver -cord 
option in maximizing cache efficiency. 
See Reducing Cache Conflicts in this 
chapter for more information. 



Figure 4.8. How PC-Sampling Works. 

Details of the steps shown in Figure 4.8 are as follows: 

1. Compile and link-edit using the — p option. For example: 

cc -c myprog. c 

cc -p -o myprog myprog , o 

Note that the -p profiling option must be specified during 
the link editing step to obtain pc sampling information. 

2. Execute the profiled program. During execution, profiling 
data is saved in the profile data file (the default is mon.out). 

myprog 

You can run the program several times, altering the input 
data, and create multiple profile data files, if you desire. 
See the section Averaging Prof Results later in this chapter 
for an example. 



c 



( 



c 
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3. Run the profile formatting program prof, which extracts 

information from the profile data file(s) and prints it in an 
easily readable format. 

prof -procedure myprog mon , out 

For more information on prof, see the prof(l) section in the 
User's Reference Manual 

You can include or exclude information on specific procedures within your 
program by using the — only or — exclude profiler options (Table 4.1). 

Creating Multiple Profile Data Files 

When you run a program using pc-sampling, raw data is collected and saved in 
the profile data file mon. out. If you wish to collect profile data in several files, 
or specify a different name for the profile data file, set the environment variable 
PROFDIR as foUows: 

C Shell Bourne Shell 

setenv PROFDIR string PROFDIR = string ; export PROFDIR 

This causes the results to be saved in the file string/pid.progname, where pid is 
the process id of the executing program and progname is its name as it appears 
in argv[0]; string is the name of a directory you must create before you run the 
program. 

Running the Profiler (prof) 

The profiler program converts the raw profiling information into either a printed 
listing or an output file for use by the compiler. To run the program, type in 
prof followed by the optional parameters indicated below: 

prof [options] [pname] { [profile__filename . . , ] | 
[pname, Addrs pname. Counts] } 

The prof parameters are summarized below: 

options is one of the keyword or keyword abbreviations shown in Table 4,1. 
(You can specify either the entire name or the initial character of the option, as 
indicated in the table.) 

pname specifies the name of your program. The default file is a.out. 

profile Jilename specifies one or more files containing the profile data gathered 
when the profiled program executed. If you specify more than one file, prof 
sums the statistics in the resulting profile listings. 

pname.Addrs (produced by running pixie) and pname. Counts (produced by run- 
ning the pixie-modified version of the program). 

The prof program takes defaults for profile_filename as follows: 

• If you don't specify profile Jilename, the profiler looks for the 
moaout file; if this file doesn't exist, it looks for the profile 
input data file(s) in the directory specified by the PROFDIR 
environment variable (see the preceding section Creating Mul- 
tiple Profile Data Files). 
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• If you don't specify profile Jilename, but do specify -pixie, 
then prof looks for p name. Addrs and pname. Counts and pro- 
vides basic block count information if these files are present. 



c 



You might wish to consider using the —merge option when you have more than 
one profile data file; this option merges the data from several profile files into 
one file. See Part 2 of Table 4.1 for information on the — merge option. 



Profile List Program (prof) Options 


Name 


Result 


-procedures] 


Lists the time spent in each procedure. 
See Figures 4.3 for a sample output listing. 


-pixie 


Basic block counting. Indicates that information is to be 
generated on basic block counting, and that the Addrs and 
Counts file produced by pixie are to be used by default. 

See Figure 2.3 through 2.6 for examples of sample output. 


-invocations] 


Basic block counting. Lists the number of times each procedure 
is invoked. The -exclude and ^-only options described below 
apply to callees, but not to callers. 

See Figure 4.2 for sample output. 


-l[ines] 


Basic block counting. List statistics for each line of source code. 
See Figure 4.6 for sample output. 


-o[nly] procjiame 


Reports information on only the procedure specified by proce- 
durejiame, rather than on the entire program. You may specify 
more than one -o option. If you specify uppercase -0, prof uses 
only the name procedure(s), rather than the entire program, as 
the base upon which it calculates percentages. 

Excludes information on the procedure(s) (and their descendants) 
specified by procedurejiame. If you specify uppercase -E for 
Exclude, prof also omits that 


-e[xclude] 
procedure jame 


Basic block counting. Prints a list of procedures that are never 
invoked. 


-z[ero] 


Basic block counting. Prints a list of procedures that are never 
invoked. 



( 



Table 4.1 (1 of 3). Options for the Profile List Program (prof). 
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Profile List Program (prof) Options 



Name 



Result 



-q 
-q 



mt 
'uit 
uit 



n 

n% 

ncum% 



Allows you to condense output listings by truncating unwanted lines. You 
can truncate by specify n in three different ways: 

n n is an integer. All Lines after n line are trun- 

cated. 

n% n is an integer followed by the percentage 

sign. All lines after the line containing n% calls 
in the %calls column are truncated. 

n n is an integer followed by the characters cum 

(for cumulative) and a percentage sign. All lines 
after the line containing ncum% calls in the 
cum% column are truncated. 

Below are three examples of using the -q option. Any one of the 
three specifications shown below would eliminate the shaded area 
shown in the shaded area of the sample listing. 

-prof -q 4 

-prof -q 13% 

-prof -q 92cum% 

calls %calls 



48071708 

42443503 

26457936 

v 20 % 662326 w 

illllill 
llllllll 

Illllill 
lllllllll 

lllliliil 

iiiiiiiii 



32.45 
28.65 
17.86 
13.95 



cum% 

32.45 

61.10 

78.96 

J2^91 v> 

lllllll 

lllllll 

lllllll 
lllllll 






111111 
llllll 

IIPIII 
llllll,,,,,,,,-,,,. 

iiiiiiiiiiiii 

llilllillilli 



llllll 



6.0090 

5.3054 

3.3072 

J2^828 w 

lllllll 

• ■;.• i$n 

lllllll 

Illllill 
Illllill 

Illllill 
Illllill 



Table 4.1 (2 of 3). Options for the Profile List Program (prof). 
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Profile List Program (prof) Options 


Name 


Result 


-h[eavy] 


Basic block counting. Same as the -lines option, but sorts 
the lines by their frequency of use. 

See Figure 4.5 for a sample output listing. 


-c[lock}z 


Basic block counting. Lists the number of seconds spent 
in each routine, based on the CPU clock frequency n, ex- 
pressed in megahertz; n defaults to 8.0 of omitted. Never 
use the default if the next argument program jtame or 
profile jiame begins with a digit. 

See Figure 4.4 for a sample output listing. 


-t[estcoverage] 


Basic block counting. Lists line numbers that contain 
code that is never executed. 


-m[cvgcjilename 


This option is useful when multiple input files of profile 
data (normally in mon.out) are used. The option causes 
the profiler to merge the input files into filename, making 
it possible to specify the name of the merged file (instead 
of several file names) on subsequent profiler runs. 


-f feedback] filename 


Produces a file used by the driver -cord option to maxi- 
mize cache efficiency. See Reducing Cache Conflicts in 
this chapter for details. 



c 



c 



Optimization 



Table 4.1 (3 of 3). Options for the Profile List Program (prof). 



This section gives background on the compiler optimization facilities and de- 
scribes their benefits, the implications of optimizing and debugging, and the ma- 
jor optimizing techniques. 

Global optimizer. The global optimizer is a single program that improves the 
performance of RISCompiler object programs by transforming existing code 
into more efficient coding sequences. Although the same optimizer processes 
all compiler optimizations, it does distinguish between the various languages 
supported by the RISCompiler system programs to take advantage of the differ- 
ent language semantics involved. 

Today, most compilers perform certain code optimizations, although the extent 
to which they perform these optimizations varies widely. The MIPS RIS- 
Compiler system performs more extensive optimizations compared with the 
average compiler available. These advanced optimizations are the results of the 
latest research into better and more powerful compiler techniques. 

The compiler system performs both machine-independent and machine-depend- 
ent optimizations. RISComputers and other machines with RISC architectures 
provide a better target for machine-dependent optimizations. This is because 



( 
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the low-level instructions of RISC machines provide more optimization oppor- 
tunities than the high-level instructions in other machines. Even optimizations 
that are machine-independent have been found to be effective on machines with 
RISC architectures. Although most of the optimizations performed by the 
global optimizer are machine-independent, they have been specifically tailored 
to the RISC/os environment. 

Benefits. The primary benefits of optimization, of course, are faster running 
programs and smaller object code size. However, the optimizer can also speed 
up development time. For example, your coding time can be reduced by leav- 
ing it up to the optimizer to relate programming details to execution time effi- 
ciency. This frees you up to focus on the more crucial global structure of your 
program. Moreover, programs often yield optimizable code sequences regard- 
less of how well you write your source program. 

Optimization and debugging. Optimize your programs only when they are 
fully developed and debugged. Although the optimizer doesn't alter the flow of 
control within a program, it may move operations around so that the object code 
doesn't correspond to the source code. These changed sequences of code may 
create confusion when using the debugger. 

Optimization and bounds checking. The compiler option — C, which per- 
forms bounds checking in Pascal programs, inhibits some optimizations. There- 
fore, unless bounds checking is crucial, you shouldn't specify the pc • — C option 
when you optimize a Pascal program. 

Loop optimization. Optimizations are most useful in program areas that con- 
tain loops. The optimizer moves loop-invariant code sequences outside loops 
so that they are performed only once instead of multiple times. Apart from 
loop-invariant code, loops often contain loop-induction expressions that can be 
replaced with simple increments. In programs composed of mostly loops, 
global optimization can often reduce the running time by half. 

The following examples show the results of loop optimization. The source code 
below was compiled with and without the — O compiler optimization option: 



void 

left (a, distance) 
char a [] / 
int distance; 

r 






l 

int j, 


length; 






length 
for ( j 
a[j] 
} 


= strlen(a) - dis 
=0; j < length; 
= a[j + distance] 


tance; 



The following listings show the unoptimized and optimized code produced by 
the compiler. Note that the optimized version contains fewer total instructions 
and fewer instructions that reference memory. Wherever possible, the optimizer 
replaces load and store instructions (which reference memory) with the faster 
computational instructions that perform operations only in registers. 
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Unopfimized: 






loop 


s 13 instructions long using 8 memory references. 


# 


8 




for (j=0; j<le 


ingth; j++) 






sw 


$0, 36($sp) 


# j = 






ble 


$24, r $33 


# length >- j 


$32: 










# 


9 




a[j] = a [ j -{-distance] ; 






lw 


$25, 36($sp) 


# j 






lw 


$8, 44($sp) 


# distance 






addu 


$9, $25, $8 


# j+distance 






lw 


$10, 40($sp) 


# address of a 






addu 


$11, $10, $9 


# address of a [j+distance] 






lbu 


$12, 0($11) 


# a [j+distance] 






addu 


$13, $10, $25 


# address of a[j] 






sb 


$12, 0($13) 


# a[j] 






lw 


$14, 36($sp) 


# j 






addu 


$15, $14, 1 


# j+1 






sw 


$15, 36($sp) 


# j++ 






lw 


$3, 32($sp) 


# length 






bit 


$15, $3, $32 


# j < length 


$33 










Optimized 


: 






loop 


is 6 instructions long using 2 memory references. 


# 


8 




for (j=0; j<length; j++) 






move 


$5, $0 


# j = 






ble 


$4, 0, $33 


# length >= j 






move 


$2, $16 


# address of a[j] 






addu 


$6, $16, $17 


# address of a [j+distance] 


$32 










# 


9 




a[j] = a [j+distance] ; 






lbu 


$3, 0($6) 


# a [j+distance] 






sb 


$3, 0($2) 


# a[j] 






addu 


$5, $5, 1 


# j++ 






addu 


$2, $2, 1 


# address of next a[j] 






addu 


$6, $6, 1 


# address of next a [ j+distance^ 






bit 


$5, $4, $32 


# j < length 


$33 








# address of nexta [j+distance] 



c 



( 



Register allocation. MIPS RISComputer architecture emphasizes the use of 
registers. Therefore, register usages have significant impact on program per- 
formance. For example, fetching a value from a register is significantly faster 
than fetching a value from storage. Thus, to perform its intended function, the 
optimizer must make the best possible use of registers. 

In allocating registers, the optimizer selects those data items most suited for reg 
isters, taking into account their frequency of use and their location in the pro- 
gram structure. In addition, the optimizer assigns values to registers so that 
their contents move minimally within loops and during procedure invocations. 

Optimizing separate compilation units. The optimizer processes one proce- 
dure at a time. Large procedures offer more opportunities for optimization, 
since more inter-relationships are exposed in terms of constructs and regions. 



c 
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However, because of their size, large procedures require more time than 
smaUer-f[eedbadgPercameones. 

The uload and umerge phases of the compiler permit global optimization among 
separate units in the same compilation. Often, programs are divided into sepa- 
rate files, called modules or compilation units, which are compiled separately. 
This saves compile time during program development, since a change requires 
recompilation of only one compilation unit rather than the entire program. 

Traditionally, program modularity restricted the optimization of code to a single 
compilation unit at a time rather than over the full breadth of the program. For 
example, calls to procedures that reside in other modules couldn't be fully opti- 
mized together with the code that called them. 

The uload and umerge phases of the compiler system overcomes this deficiency. 
The uload phase links multi-compilation units into a single compilation unit. 
Then, umerge orders the procedures for optimal processing by the global op- 
timizer (uopt). 



Optimization Options 



Figure 4.10 on the next page shows the major processing phases of the compiler 
and how the compiler — On option determines the execution sequence. The 
table belows summarizes the functions of each of the — O options. 



ption Result 



CM 



— 03 The ulink and umerge phases process the output from 

the compilation phase of the compiler, which produces 
symbol table information and the program text in an 
internal format called ucode. 

The ulink phase combines all the ucode files and sym- 
bol tables, and passes control to umerge. Umerge reor- 
ders the ucode for optimal processing by uopt. Upon 
completion, umerge passes control to uopt, which per- 
forms global optimizations on the program. 

— 02 Ulink and umerge are bypassed, and only the global 

optimizer (uopt) phase executes. It performs optimiza- 
tion only within the bounds of individual compilation 
units. 

— Ol Ulink, umerge, and uopt are bypassed. However, the 

code generator and the assembler perform basic opt- 
imizations in a more limited scope. 

— 00 Ulink, umerge, and uopt are bypassed, and the assem- 

bler bypasses certain optimizations it normally per- 
forms. 

NOTE: The — 03 options is not available for the cobol driver when the edi- 
tion of this manual was printed. You should refer to the cc(l) f77(l) pll(l), or 
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pc(l) manual page, as applicable, in the User's Reference Manual for details on 
the -03 option and the input and output files related to this option. 



c 



Compilation 1 




Procedure Merge 

(urnerge) 



-02 



-01 







Link Editor 



*™^ f™1 Assemble 
l—J object fih 



e; • . 



□ Llnkad • 
object file. 



a.out 



( 



Figure 4.10. Optimization Phases of the Compiler. 
Full Optimization (-03) 

This section provides examples using the -03 option. The examples given as- 
sume that the program foo consists of three files: a.c, b.c and a.c. 

To perform procedure merging optimizations (-03) on all three files, type in the 
following: 

% cc -03 -o f oo a . c b . c c . c 

If you normally use the — c option to compile the .o object file, follow these 
steps: 

1. compile each file separately using the — j option by typing in the 
following: 

% cc - j a. c 
% cc - j b.c 

% cc - j c . c 

The — j option causes the compiler driver to produce a .u file (the 
standard compiler front-end output, which is made up of ucode; 



( 
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ucode is an internal language used by the compiler). None of the 
remaining compiling phases are executed, as illustrated below. The 
figure below illustrates the results after execution of the three com- 
mands shown above. 



nnn 

a.c b.c c.c 








C Compiler 




nnn 

a.u b.u c.u 





2. Enter the the following statement to perform optimization and com- 
plete the compilation process. 

% cc -03 -o foo a.u b.u c.u 

The figure below illustrates the results of executing the above state- 
ment. 



a.u b.u c.u 




Procedure Merge 
(umerge) 



Global Optimizer 
(uopt) 




Link Edit 



foo 



Optimizing Large Programs 



If you wish to ensure that all program modules are optimized regardless of size, 
specify the driver — Olimit option at compilation. 

Because compilation time increases by the square of the program size, the JKS-/ 
Compiler system enforces a top limit on the size of a program that can be opti- 
mized. This limit was set for the convenience of users who place a higher pri- 
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ority on the compilation turnaround time than on optimizing an entire program. 
The — Olimit option removes the top limit and allows those users who don't 
mind a long compilation to fully optimize their programs. 



Optimizing Frequently Used Modules 



You may want to compile and optimize modules that are frequently called from 
programs written in the future. This can reduce the compile and optimization 
time required when the modules are needed. 

In the examples that follow, hx and ex represent two frequently used modules 
that you wish to compile and optimize, retaining all the necessary information 
to link them with future programs; future.c represents one such program. 

1. Compile hx and ex separately by entering the following statements: 

% cc - j b. c 
% cc - j c .c 

The — j option causes the front end (first phase) of the compiler to 
produce two ucode files b.u and c.u. 

2. Create manually a file containing the external symbols in b.c and 
cc to which futurex will refer. Each symbolic name must be sepa- 
rated by at least one blank. Consider the following skeletal contents 
of hx and ex. 



b.c 


foo() 


CC x ( ) 




{ 


{ 




• 


• 




• 


• 




} 

bar() 


} 

help() 




{ 


{ 




• 


• 




• 


• 




} 

zot() 


} 
struct 




{ 


{ 




• 


• 




• 


• 




} 


} ddata; 




struct 


y() 




{ 


{ 




• 


• 




• 


• 




} work; 


} 



c 



In this example, futurex will call or reference only foo, bar, x, 
ddata, and y in the hx and ex procedures. A file (named extern for 
this example) must be created containing the following symbolic 
names: 

f oo bar x ddata y 



( 



4-22 



Languages Programmer's Guide 



Improving Program Performance 



(The structure work, and the procedures help and zot are used inter- 
nally only by bx and cc, and thus aren't included in extern.) 

If you omit an external symbolic name, an error message is gener- 
ated (see Step 4 below). 

3. Now, optimize the b.u and c.u modules (Step 1) using the extern 
file (Step 2) as follows: 

% cc -c -03 -kp extern b . u c . u -o keep . o 

In the — kp option, k designates that the link editor option p is to be 
passed to the ucode loader. 

The figure below illustrates Step 3. 



b.u c.u 




Ucode Link 
(uld) 



extern 

(hand-created 
symbol list file) 



Procedure Merge 
(umerge) 




Global Optimizer 
("opt) 



Code Generator I 




Assembler 



keep.o 



4. Create a ucode file and an optimized object code file (foo) for fu- 
turex as follows: 

% cc — j future . c 

% cc -03 future . u keep . o — o foo 

The following message may appear; it means that the code in fu- 
ture.c is using a symbol from the code in b.c or b.c that was not 
specified in the file extern. 

zot : multiply defined hidden external (should have been 
preserved) 

Go to Step 5 if this message appears. 
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5. Include zot, which the message indicates is missing, in the file ex- 

tern and recompile as follows: | 



% cc -03 -c -kp extern b.u c .u -o keep.o 
% cc -03 future . u keep . o -o f oo 



Building a Ucode Object Library 



Building a ucode object library is similar to building a coff object library. First, 
compile the source files into ucode object files using the compiler driver option 
-j and using the archiver just as you would for coff object libraries. Using the 
above example, to build a ucode library (lib/oab), type in the following: 

% cc - j a. c 
% cc -j b.c 
% cc-j c.c 
% ar crs libf oo .b a,u b .u c .u 

Conventional names exist for ucode object libraries (libx.fr) just as they do for 
coff object libraries (libx.a). 



Using Ucode Object Libraries 



Using ucode object libraries is similar to using coff object files,a To load from 
a ucode library, specify a -klx option to the compiler driver or the ucode loader. 
For example, to load from the ucode library the file created in the previous ex- 
ample, type in the following: 

% cc -03 f ilel .u f ile2 .u -klfoo -o output 

Remember that libraries are searched as they are encountered on the command 
line, so the order in which you specify them is important. If a library is made 
from both assembly and high level language routines, the ucode object library 
contains code only for the high level language routines and not all the routines 
as the coff object library. In this case, you must specify to the ucode loader 
both the ucode object library and the coff object library, in that order to ensure 
that all modules are loaded from the proper library. 

If the compiler driver is to perform both a ucode load step and a final load step, 
the object file created after the ucode load step is placed in the position of the 
first ucode file specified or created on the command line in the final load step. 



Improving Global Optimization 



c 



This section contains coding hints recommended to increase optimizing oppor- 
tunities for the global optimizer (uopt). You should read through the recom- 
mendations in this section and, where possible, apply them to your code. 

C, Pascal and FORTRAN Programs 

Do not use indirect calls. Avoid indirect calls (calls that use routines or point- 
ers to functions as arguments). Indirect calls cause unknown side effects (that 
is, change global variables) that can reduce the amount of optimization. I 
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C and Pascal Programs 



Function return values. Use functions to return values instead of reference 
parameters. 

Do while and repeat. Use do while (for C) and repeat (for Pascal) instead of 
while or for when possible. For do while and repeat, the optimizer doesn't 
have to duplicate the loop condition in order to move code from within the loop 
to outside the loop. 

Unions and variant records. Avoid unions (in C) and variant records (in Pas- 
cal) that cause overlap between integer and floating point data types. This 
keeps the optimizer from assigning the fields to registers. 

Use local variables. Avoid global variables. In C programs, declare any vari- 
able outside of a function as static, unless that variable is referenced by another 
source file. Minimizing the use of global variables increases optimization op- 
portunities for the compiler. 

Value parameters. Use value parameters instead of reference parameters or 
global variables. Reference parameters have the same degrading effects as the 
use of pointers (see below). 

Pointers and aliasing. Aliases can often be avoided by introducing local vari- 
ables to store dereferenced results. (A dereferenced result is the value obtained 
from a specified address.) Dereferenced values are affected by indirect opera- 
tions and calls, whereas local variables aren't. Therefore, they can be kept in 
registers. The following example shows how the proper placement of pointers 
and the elimination of aliasing lets the compiler produce better code. 
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General Compiler Options 



Option Name 



-std 



-U name 



_v 



-pi or -p 



Purpose 



Similar to -c, except produces assembly code in a .s 
file instead of object code in a .0 file. 

Issues a warning message when the compiler finds a 
non-standard feature in the programming language 
of your source program. 

Overrides a definition of a macro name that you speci- 
fied with the -D option, or that is defined automatically 
by the driver. 

Lists compiler phases as they are executed. Use this 
option when you suspect a phase isn't being run as 
you intended. For example, the option might reveal 
that you failed to specify a library required by the 
link editor. For BSD 4.3 users, this option also 
prints resource usage of each phase. 

Prints the version number of the driver and its phases. 
When reporting a suspected compiler problem, you 
must include this number. 

Suppresses warning messages. 

Permits program counter (pc) sampling. This option 
provides operational statistics for use in improving 
program performance. See Chapter 4 for more de- 
tails. 

Note: This option affects only the link editor and is 
ignored by the compiler front ends. When link edit- 
ing as a separate step from compilation,, be sure to 
specify this option if pc sampling is desired. 



c 



c 



( 
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Consider the following example, which uses pointers. Because the statement 
*p++=0 might modify len, the compiler, for optimal performance, cannot place 
it in a register, but instead must load it from memory on each pass through the 
loop. 



Source Coda: 

iat l^n « 10; • " ' • i 

char a [10 3; 

llllllllllllllllllllllllllllllll 
•ze.ro O 

char *p; 

far (p « a; p !« a + len; ) 

Generated Assembly Coda: 



^p++ = 0; 



11111 



liili: 



iiiii 



£03' <p ; 
.move 
1 lw 
addu 
beq 

addu 

1 lw 
addu 

bnei 



a; p !» a 4 left; ) 



$2, $4 

$3, len Iiiii! 

•$24 # $% t ;$s 

$2, $2 / 1 
$25, len 

38, $4 # $25 i 
$&, $2, -$32 



HI 



lilll 

- a 



lii 



a -f len [« £ 

lilltlll 



liiili 



I M 4 a> p: 



Two different methods can be used to increase the efficiency of this example: 
using subscripts instead of pointers and using local variables to store unchang- 
ing values. 

Using subscripts instead of pointers. The use of subscripting in the procedure 
azero eliminates aliasing; the compiler keeps the value of len in a register, sav- 
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ing two instructions, and still uses a pointer to access a efficiently, even though 
a pointer isn't specified in the source code. 



c 



Source Codes 

void , I 

azero () ' 

, int i; 

for {I ~ 0; i 1 ; 



lea; i-K) a[i]| 



9^B9i^^B3M^^K 



$36, 



111 



,£o£ (i « 0; i !■« l«n; i++) ati] « 0, 



move 


llil|l 


$0 


# i - 


beq 


'$4, 


0, $37 


iiliiiiiiliiili 


la 


lllll 


lllllllllllll 




Ifllll 


11111 


illllllli 


# *a •=■ 


addu 


$2 r 


$2, 1 


.#1+4- 


addu 


$5, 


$5, i 


' # a++ 


bne 


IWI1 


lllllllill 


# i 3= len 



Using local variables. Specifying Z<?ft as a local variable or formal argument 
(as shown below) ensures that aliasing can't take place and permits the compiler 
to place len in a register. 



( 



Source Codes 






'Char a [10] ; 






IlilllM 






Ipzero (len) . 






int len; !!!|:f!!|| 






char *p; 






for {p - a; p !- a 4- len; 5 *p+i 


- - 0; 




Generated Assembly Code : 






f 8 for (p " a; p !- a + kn? ) 


*P++ » 0; 




move ' $2, $& 


# p ^ a 




addu $5, $6, $4 






beq $5, $6, $33 


lliljiiiijiliilii 


r= a 


•:..$32^\.t./-.. -;::\. : . ,'..:::••••;••. : -'' : :.,:. -..- : :••••, • 






sb $0, Q{$2) 


# *p * 




addu $2, $2, a 


* P*+ 




bne $5, $3, $32 


# a 4- len 


I 035 p 


^M^^^^^^^^^^^^^^^^M 







In the previous example, the compiler generates slightly more efficient code for 
the second method. 
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Pascal Programs Only 



C Programs Only 



Packed arrays. Packed arrays prevent moving induction expressions from 
within a loop to outside the loop. Use packed arrays only when space is crucial. 



Write straightforward code. For example, don't use ++ and — operators 
within an expression. When you use these operators for their values rather than 
for their side-~effects, you often get bad code. 

For example: 



Bad 


Good 


while (n— ){ 
} 


while (n != ) { 

n — ; 

} * ' ' 



Use register declarations liberally. The compiler automatically assigns vari- 
ables to registers. However, specifically declaring a register type lets the com- 
piler make more aggressive assumptions when assigning register variables. 

Addresses. Avoid taking and passing addresses (& values). This can create 
aliases, make the optimizer store variables from registers to their home storage 
locations, and significantly reduce optimization opportunities that would other- 
wise be performed by the compiler. 

VARARGs. Avoid functions that take a variable number of arguments. This 
causes the optimizer to unnecessarily save all parameter registers on entry. 

Improving Other Optimization 

The global optimizer processes programs only when you explicitly specify the 
— 02 or — 03 option at compilation. However, the code generator and assem- 
bler phases of the compiler always perform certain optimizations (certain assem- 
bler optimizations are bypassed when you specify the — 00 option at compila- 
tion). 

This section contains coding hints that, when followed, increase optimizing op- 
portunities for the other passes of the compiler. 

C, Pascal, and FORTRAN Programs 



1. Use tables rather than if-then-else or switch statements. 

For example: 



OK 


More Efficient 


if ( i == l) c = "1"; 
else c « "0"; 


c - "01" [i] ; 



As an optimizing technique, the compiler puts the first four 
parameters of a parameter list into registers where they re- 
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main during execution of the called routine. Therefore, you 
should always declare as the first four parameters those 
variables that are most frequently manipulated in the called 
routine with floating point parameters preceding non-float- 
ing point. 

3. Use word-size variables instead of smaller ones if enough 

space is available. This may take more space but it is more 
efficient. 



Rely on libc functions (for example, strcpy, strlen, strcmp, 
bcopy, bzero, memset, and memcpy). These functions were 
hand-coded for efficiency. 

Use the unsigned data type for variables wherever possible 
for the following reasons: (1) because it knows the variable 
will always be greater than or equal to zero (>=0), the com- 
piler can perform optimizations that would not otherwise be 
possible, and (2) the compiler generates fewer instructions 
for multiply and divide operations that use the power of 
two. Consider the following example: 

int i; 
unsigned j; 

return i/2 + j/2; 

The compiler generates six instructions for the signed i/2 
operations: 

000000 20010002 li rl,2 

000004 0081001a divr4,rl 

000008 14200002 bnerl, r0, .0x14 

00000c 00000000 nop 

000010 03fe000dbreak 1022 

000014 00001812 mflo r3 

The compiler generates only one instruction for the un- 
signed j/2 operation: 

000018 0005c042 srlr24,r5,l #j/2 

In the example, i/2 is an expensive expression; however, j/2 
is inexpensive. 
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c 



Predefined functions. Use predefined functions as much as possible. For ex- 
ample, 

• use max and min rather than if-then-else, 

■• Also, use shift and bit-wise and instead of div and mod. 



( 
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Limiting the Size of Global Data Area 



The compiler places constants and varialbes in the Ait8, .lit4, .sdata and .sbss 
portions of the data and bss segments shown in the figure below. This area is 
referred to as the global data area. 







.text. . 


iHlliiiiill 


.fdata 


!i!f 


f> data segment 


.data 




.lite 


111 




.Iit4 






.sdata 


I 


.sbss 




>KSKbM\>t^ 


1 


Sill 


3 Global polntei 


*ama 



(The sdata, .data, Mt8, iit4, and .sdata sections contain initialized data, and the 
.sbss and .bss sections reserve space for uninitialized data that is created by the 
kernel loader for the program before execution and filled with zeros. For more 
information on section data, see Chapter 10 of the Assembly Language Pro- 
grammer's Guide.) 

Purpose of Global Data 

In general, the compiler system emits two machine instructions to access a 
global datum. However, by using a register as a global pointer (called $gp), the 
compiler creates the 65536-byte global data area where a program can access 
any datum with a single machine instruction — only half the number of instruc- 
tions required without a global pointer. 

To maximize the number of individual variables and constants that a program 
can access in the global data area, the compiler first places those variables and 
constants that take the fewest bytes of memory. By default, the variables and 
constants occupying eight or fewer bytes are placed in the global data area, and 
those occupying more than eight bytes are placed in the .data and .bss sections. 

Controlling the Size of Global Data Area 

The more data that the compiler places in the global data area, the faster a pro- 
gram executes. However, if the data to be placed in the global data area ex- 
ceeds 65536 bytes, the link editor prints an error message and doesn't create an 
executable object file. For most programs, the eight-byte default produces opti- 
mal results. However, the compiler provides the -G option to let you change 
the default size. For example, the specification 

— G12 
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causes the compiler to place only those variables and constants that occupy 12 ^ 

or fewer bytes in the global data area. I 

Obtaining Optimal Global Data Size 

The compiler places some variables in the global data area regardless of the set- 
ting of the — G option. For example, a program written in assembly language 
may contain .sdata directives that cause variables and constants to be placed into 
the global data area regardless of size, Moreover, the — G option doesn't affect 
variables and constants in libraries and objects compiled beforehand. To alter 
the allocation size for the global data area for data from these objects, you must 
recompile them specifying the — G option and the desired value. 

Thus, two potential problems exist in specifying a maximum size in the — G 
option: 

• Using a value that is too small can reduce the speed of the pro- 
gram. 

• Using a value that is too large can cause more than the maxi- 
mum 65536 bytes to be placed in the data area, creating an er- 
ror condition and producing an unexecutable object module. 

The link editor —bestGnum option helps overcome these problems by predict- 
ing an optimal value to specify for the — G option. The next sections give ex- 
amples of using the — bestGnum option and the related — nocount and 
—count options. 



Examples (Excluding Libraries) 

When using the —bestGnum option exclusive of —nocount and —count, the 
compiler driver assumes that you cannot recompile any libraries to which it 
would link automatically; the driver causes the link editor not to consider these 
libraries when predicting the optimal maximum size. However, if you link to 
other system-supplied libraries, you must specify -nocount before the library. 
For example: 

cc -bestGnum f oo . c -nocount -lm 

If you specify the option as shown below; 

pc —bestGnum bogus . p 

the compiler produces a message giving the best value for — G; if all program 
data fits into the global data area, a message indicates this. JFor example: 

All data will fit into the global data area 

Best -G num value to compile with is 80 (or greater) 

Because all data fits into the global data area, no recompilation is necessary. 
Consider the following example, which specifies 70000 as the maximum size of 
a data item to be placed in the global data area: 

pc ersatz .p -G 70000 —bestGnum 
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The above example produces the following messages: 

gp relocation out-of -range errors have occurred and bad 
object file produced (corrective action must be taken) 
Best -G num value to compile with is 1024 

In this example, the link editor doesn't produce an executable load module and 
recommends a recompilation as specified below: 



pc real.p -G 1024 

Example (Including Libraries) 



You can explicitly specify that the link editor either include or exclude specific 
libraries in predicting the — G value. Consider the following example: 

cc -o plotter -bestGnum plotter . o -nocount libieee . a 
-count liblaser . a 

In the above example, the link editor assumes that libieee, a cannot be recom- 
piled and will continue to occupy the same space in the global data area. It as- 
sumes that plotter.o and liblaser, a can be recompiled and produces a recom- 
mended — G value to use upon recompilation. 

Reducing Cache Conflicts 

RISComputer hardware provides two high-speed caches — one for program data 
and the other for instructions — that temporarily hold data or instructions fre- 
quently used by the processor. During execution, instruction or data from speci- 
fied memory locations are placed in the cache. Because the cache is much 
smaller than memory, a single cache location is shared by many distinct mem- 
ory locations. The first cache location is shared by the Oth, 64KBth, 128KBth, 
... memory locations. This mapping of every memory location to exactly one 
cache location is called a direct mapped cache. 

A cache conflict occurs when a program references two instructions or data 
items that compete for the same location in the respective data or instruction 
cache. Normally this in no problem, except when the references are made re- 
peatedly, as in a loop. Such repeated hits can degrade performance. 

A serious instruction conflict could occur if, from within a loop, a call is made 
to a function that is a multiple of the cache size away. Basically, the function is 
placed in the cache, removing the instructions from the calling loop. Upon re- 
turn, the calling loop replaces the instructions of the function, and this continues 
until the end of the loop. 

You can eliminate major instruction cache misses within your programs by us- 
ing the — cord driver option in combination with the pixie and prof programs. 
This option attempts to place the most frequently executed sections of code in 
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memory so that they don't conflict with each other. Here are the processing 
steps necessary to implement the —cord option: 



c 



1 
2 
3 

4 
5 

6 



f77 -c -0 index. f 

£77 -o index index. o 

pixie -o index .pixie index 

index. pixie 

prof index -feedback feedfile 

f77 -o index index. o -feedback feedfile 



-cord 



The figure below illustrates the steps shown in the example for the reorganiza- 
tion of the procedures compiled from the source program index f. 



ill! 














_*. index,o 


IlllMil 


compile 


2 
3 

lllllll 

III!! 
1111 








■mrnm. 




link 


#$$ 
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iiiiiiiiii 








i||| 
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****** feedfile 


^y-mm zmassm :a:- : ^:?: x m-^-y-m 




link 












iiiiiii 




WmW&WMM llllii^^ 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^MM&MB 



( 



For more information, see the prof(l), pixie(l), or the —cord option in the ap- 
plicable driver manual page — cc(l) ? pc(l), f77(l), pll(l), or cobol(l>— in the 
User's Reference Manual 



Filling Jump Delay Slots 



In jump instructions, there is a jump delay or latency of one instruction, which 
is called a jump delay slot Whenever possible, the compiler inserts an instruc- 
tion in the delay slot to avoid stalls in the execution pipeline of instructions. 
(See delay slot in the MIPS R2000 RISC Architecture manual for a detailed dis- 
cussion.) The — jmpopt enables the compiler to fill additional delay slots at the 
cost of requiring more memory by the link editor. The default is nojmpopt. 



( 
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For programs requiring the ultimate in performance, you should specify the 
— jmpopt. Then, the link editor attempts to insert executable instruction into 
those delay slots that that the compiler could not fill. 
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Debugging Your Code 



This chapter describes the source-level debugger DBX and tells how to use it. 
The debugger works for C, FORTRAN 77, Pascal, assembly language, and ma- 
chine code. This chapter provides both reference and guide information on op- 
erating the debugger; the dbx(l) manual page in the UNIX Programmer's Man- 
ual provides additional reference information. The following topics are covered 
in this chapter: 

Introduction. Introduces new users to the debugger and discusses general de- 
bugging issues, including where to start and how to isolate errors. It gives tips 
to people who are new to source-level debugging. If you're experienced at us- 
ing debuggers, you might want to skip this part. 

Running DBX. Shows how to run the debugger, including how to compile a 
program for debugging, and how to invoke and quit DBX. 

Using DBX Commands. Describes the command syntax, expression prece- 
dence, data types, and constants, and lists the most common commands. 

Working with the DBX Monitor. Describes how to use history, edit the com- 
mand line, type multiple commands, and use facilities that help you complete 
program symbol names. 

Controlling DBX. Describes how to work with variables, how to create com- 
mand aliases, record and playback input and output, invoke a shell from DBX, 
and use the DBX status feature. 

Examining Source Programs. Shows you how to specify source directories, 
move to a specified procedure or source file, list source code, search through the 
source code, call an editor from DBX, print symbolic names, and print type dec- 
larations. 

Controlling Your Program. Describes how to run and rerun a program, exe- 
cute single lines of code, return from procedure calls, start at a specified line, 
continue after a breakpoint, and assign values to program variables. 

Setting Breakpoints. Describes how to set and remove breakpoints and con- 
tinue executing a program after a breakpoint. 

Examining Program State. Describes how to print stack traces, move up and 
down the activation levels of the stack, print register and variable values, and 
print information about the activation levels in the stack. 

Debugging at the Machine Level. Describes the command that you use to de- 
bug machine code, including how to examine memory addresses and disassem- 
ble source code. 

Languages Programmer's Guide 5-1 



Chapters 



Introduction 



This section introduces the debugger and some debugging concepts; it also 
gives you some tips about how to approach a debugging session, including 
where to start, how to isolate errors, and how to avoid some common pitfalls. 

If you're an experienced user, you may want to skip this section and go to the 
DBX Command Summary section at the end of the chapter, which contains a 
reference summary of all debugger commands. 



Why Use a Source-Leva! Debugger? 



A source-level debugger like DBX lets you trace problems in your program 
object at the source code, rather than at the machine code level. With DBX, 
you control a program's execution, symbolically monitoring program control 
flow, variables, and memory locations. You can also use DBX to trace the 
logic and flow of control to acquaint yourself with a program written by some- 
one else. 

The figure below summarizes the capabilities of DBX. 



( 



Easy-to-use 
Environment 



High-level 
Language 
Debugging 



Remote 
Debugging 



Stack 
Tracing 



Single 
Stepping 





Expression 
Evaluator 




Breakpoints 




Program State 
Examination 



Line-by-line 
Variable Tracing 



c 



( 
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What Are Activation Levels? 



This chapter frequently refers to the term activation level. Activation levels de- 
fine the currently active scopes (usually procedures) on the stack. An activa- 
tion stack is a list of calls that starts with the initial program (often main). The 
most recently called procedure or block is numbered 0. The next procedure 
called is numbered 1. The last activation level is always the main program — - 
that is, the program that controls your whole program. 

Activation levels can also consist of blocks that define local variables within 
procedures. You see activation levels when you do stack traces (see the where 
command) and when you move around the activation stack (see the up, down, 
and func commands). The example below shows the result of a where com- 
mand. 

Example: 



>0 Printline (pline = 0x7f f f 5b80) Psam. c" : 58, 0x2f 7] 

Printline is the most recently called 
procedure from $blockl. 

1 $blockiPsam.c" :47,0x2bb] 

$sblockl defines its own local variables, 
even though it is part of main. 

2 main(argc = 2, argv = 0x7f ff ebaO) ["sam. c" : 47, 0x2bb] 

main is the main program. 



Isolating Program Failures 

DBX finds only runtime errors — you should fix compile errors before you start 
a debugging session. 

To save time, you should start a debugging session using the more general com- 
mands (listed below), rather than debugging line by line. For example, if a pro- 
gram fails during execution, you would: 

1. Invoke the program under DBX. 

2. Do a stack trace using the where command to locate the point of failure. 

NOTE: If you haven't stripped symbol table information from your pro- 
gram object, you can do a stack trace even when you don't compile your 
program with the debug flag -g. 

3. Set breakpoints to isolate the error, using the stop commands. 

4. Print the values of variables to see where a variable might have gone awry, 
using the print command. 

If you still cannot find your error, you need to use other commands. Using 
DBX Commands in this chapter describes how to use each command. 
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Incorrect Output Results g- 

If a program successfully terminates, but produces incorrect values or output, ^- 

follow these steps: 

1. Set a breakpoint where you think the problem is happening — for example, 
the code that generates the value or output. 

2. Run the program. 

2. Do a stack trace using the where command. 

3. Print the values for the variables that you think might be causing the prob- 
lem. Use the print command. 

4. Return to Step 1 until you find the problem. 
Avoiding Some Pitfalls 

The debugger cannot solve all problems. For example, if your program has a 
bad algorithm or incorrect logic, the debugger can only help you find the prob- 
lem, not solve it. When information displayed by the debugger appears confus- 
ing or incorrect, taking the action listed below may correct the situation: 

• Separate lines of source code into logical units wherever possi- 
ble (for example, after if conditions); the debugger might not 
recognize a source statement written with several others on the 
same line. 

• If executable code appears to be missing, it may have been con- 
tained in an include file. The debugger treats include files as a 
single line. If you wish to debug this code, remove it from the 
include file and compile it as part of your program. 

• Make sure you recompile the source code after changing it, oth- 
erwise the source code displayed by the debugger won't match 
the executable code. 

• If you stop the debugger by pressing CTRL-Z, and then resume 
the same debugging session, the debugger continues with the 
same object module specified at the start of the session. This 
means that, if you stop the debugger to fix a problem in your 
code, recompile, and return, the debugger won't reflect the 
change. You must start a new session as described in the sec- 
tion Invoking DBX (dbx). 

• When printing an expression that has the same name as a dbx 
keyword, you must enclose the expression within parentheses. 
For example, in order to print output, a keyword in the play- 
back and record commands, you must specify: 

print (output) 
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• If the debugger won't display any variables and executable 
code, make sure you compiled the program with the appropriate 
-g compiler flag. 

Running DBX 

This part of Chapter 5 describes how to run DBX, including how to do these 
things: 

• compile your program for debugging 

• create a command file 

• invoke DBX from the shell 

• end your debugging session 
Compiling Your Program for Debugging 

To use the debugger, you need to specify the -g option at compilation as de- 
scribed in Chapter 1. This option inserts symbol table information in your pro- 
gram object, which DBX uses to list source lines, 

Don't optimize your program until it is fully developed and debugged. Al- 
though the optimizer doesn't alter the flow of control within a program, it may 
move operations around so that the object code doesn't correspond to the source 
code. These changed sequences of code may create confusion when you use the 
debugger. 

You can do limited debugging on code compiled without the -g flag. These 
commands still work without -g: 

stop in PROCEDURE 

stepi 

continue 

conti 

(ADDRESS)/<COUNT><MODE> 

tracei 

Although you can do limited debugging on this code, you will have an easier 
time if you recompile the code for debugging. The debugger does not warn you 
when you select an object file that you compiled without the -g flag. 

Building a Command File 

You can create a command file, called the .dbxinit file, using the system editor. 
You can put any DBX command in the file; when you invoke DBX, the com- 
mands are executed (you'll be prompted for required input). You can use a 
command file to customize your DBX environment or to specify a set of fre- 
quently used DBX commands. 
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DBX looks for .dbxinit first in the current directory and then in your home di- 
rectory. If the file resides in the home directory, set the UNIX system HOME 
environment variable. 

Here's an example of a .dbxinit file: 



( 



set $page - 5 
set $lines = 20 
set $prompt = "DBX>' 
alias du dump 



Invoking DBX (dbx) 



You invoke DBX from the shell command line by entering dbx and the optional 
parameters shown below. After invocation, DBX sets the current function to 
the first procedure of the program. 

Syntax: 



Command 


Select this command to.. 


dbx [options] [objfile corefile] 


Invoke DBX from the 
shell command line. 



If you don't explicitly specify object Jile, DBX uses a.out by default. If you 
specify corejile, DBX lists the point of program failure. For core files, you 
can do stack traces and look at the code; however, you cannot run a program 
continuously — for example, set breakpoints or continue. 

The options specifications are shown in the following table. 



Option 


Select this option to... 


-I dirname 

-c filename 
-4 

-r 
-* 


Tell DBX to look in the specified directory for source 
files. To specify multiple directories, you must use a 
separate -I for each. Unless you specify this option 
when you invoke DBX, it looks for source files in the 
current directory and in the object file's directory. 
From DBX, you can change directories with the use 
command. 

Select a command file other than your dbxinit file. 

Use interactive mode. This option does not treat #s as 
comments in a file. It also prompts for source even 
when it reads from a file. It has extra formatting as if 
for a terminal. 

Run your program immediately upon entering DBX. 
Turn on kernel debugging. 



( 



( 
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Example: 



% dbx 




dbx version 3 of 3/30/86 14:51 




Type 'help' for help. 




enter object file name (default is 'a. out'): 


sam 


reading symbolic information... 




main: 23 if (argc <2) { 




(dbx) 





Ending DBX (quit) 



Use the quit command to end a debugging session. 
Syntax: 



Command 


Select this command to..* 


quit 
q 


End your debugging session. 



Example: 



(dbx) quit 



In the above example, after entering quit, DBX prompts you to confirm that you 
want to exit. 



Using DBX Commands 

This part of Chapter 5 covers these topics: 

• command syntax 

• expression and precedence 

• data types and constants 

• common debugging commands 
DBX Command Syntax 



This section describes the format of DBX commands. The following general 
conventions are used in each description: 

• Words in lower-case typewriter font are literals, and you must 
type them as they are shown. 

• Words in italics indicate variable values that you specify. 

• Square brackets ([]) surrounding an argument mean that the ar- 
gument is optional. 
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DBX variable names appear in italics. 



DBX lets you type up to 10240 characters on an input line. 



( 



• You can continue long lines with a backslash (\). If the line 
gets too long, DBX prints an error message (see fgets(l) in the 
UNIX Programmer's Manual). 

• The maximum string length is also 10240. 

In addition to these general conventions, the words in upper-case typewriter 
font indicate variables for which specific rules apply. These words are given in 
the Table 5. 1 on the next page. 

The example below of the stop in command illustrates the syntax conventions 
just described: 

stop VAR in PROCEDURE if EXP 

You would type stop, in, and */as shown. You would type the values for VAR, 
PROCEDURE and EXP as defined in Table 5.1. 



Syntax 


You specify: 


FILE 


Filename. 


INT 


Integer value. 


EXP 


Any expression including program variable names for 
the command. Expressions can contain DBX vari- 
ables; for example, ($listwindow + 2). If you want to 
use the words in, to or at in an expression, you must 
surround them with parentheses; otherwise, DBX as- 
sumes that these words are debugger key words. 


PROCEDURE 


Procedure name or an activation level on the stack. 


LINE 


A source code line number. 


A (caret) 


Press the control key on your keyboard. Usually, 
you do as you simultaneously press another key. 


ADDRESS 


Any expression specifying a machine address. 


REGEX 


A regular expression string. See the ed(l) manual 
page in the UMIPS Programmer's Manual 


SIGNAL 


A UNIX system signal. For Berkely, see the sigvec(2) 
manual page in XhilMIPS Programmer's Manual. 
For Systemv, see the signals(2) manual page. 



( 



Table 5.1 (1 of 2). Keywords Used in Command Syntax Descriptions. 



( 
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Syntax 


You specify: 


STRING 


Any ASCII string. 


DIR 


A directory name. 


ARGS 


Program arguments (maximum allowed by DBX is 1000; 
however, system limits may also apply). 


VAR 


Valid program variable or DBX predefined variable (see 
Table 5.2). For machine-level debugging, VAR can 
also be an address. 




You must qualify program variables with duplicate names 
as described in the section Qualifying Variable Names. 


NAME 


DBX command name. 


COMMAND JJST 


One or more commands, each separated by semicolons. 



Table 5 J (2 of 2). Keywords Used in Command Syntax Descriptions. 



Qualifying Variable Names 



DBX qualifies your variables by the file, the procedure, a block, or a structure. 
When you use commands like print to print a variable's value, DBX tells you 
the scope of the variable when the scope could be ambiguous (for example, you 
have a variable by the same name in different procedures). If you see the 
wrong variable, you can specify the full scope of your variable manually by 
separating scopes with periods. 

Example: 



sam.main.i 



.variable 



current 
file 



procedure 



DBX Expressions and Precedence 



DBX recognizes expression operators from C, Pascal, and FORTRAN 77. Op- 
erators follow the C language precedence. 
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Debugger Operators 


Operator 


Syntax 


Description 


# 


("FILE" #EXP) 

(PROCEDURE #EXP) 
(#EXP) 


Uses the specified line 
number (#EXP) in that 
file. 

Uses the specified line 
number (#EXP) in that 
procedure* 

Takes line number 
(#EXP) and returns 
the address for that 
line. 



The following tables show language operators; note that // (instead of [) is used 
for divide. 



C Language Operators 



Unary 
Binary 



&, +, -, *, stzeofO -, /A (type), (type *) 

t, I, 11,+,-,*, %,[],-> 



CAUTION: The sizeof operator specifies the number of bytes retrieved to get 
an element, not (/number_ofjDits+7)/8. 



Pascal Language Operators 



Unary 
Binary 



not, r- 

X~, >~, < >, and, or, +, ~-, 
*,//„div,mod,[],., " 



FORTRAN Operators 



Unary 
Binary 



+.-,*.// 



NOTE: FORTRAN array subscripting must use [] instead of (). 

DBX Data Types and Constants 

DBX commands can use the following built-in data types: 



c 
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Data Types 


Data Types 


Description 


$address 


pointer 


$unsigned 


unsigned integer 


$char 


character 


Sboolean 


boolean 


$real 


double precision real 


$integer 


signed integer 


$float 


single precision real 


$double 


double precision real 


$uchar 


unsigned character 


$short 


16-bit integer 



You can also use the built-in data types for type coercion— for example, to see 
a variable as a type that the language you're using doesn't support. 



Input Constants 


Constant 


Description 


false 





true 


nonzero 


nil 





Ox number 


hexadecimal 


OXnumber 


decimal 


Onumber 


octal 


number 


decimal 


number. .[number] [elE][+l-EXP] 


float 



NOTE: Overflow on non-float uses the right-most digits. Overflow on float 
uses the left-most of the mantissa and the highest or lowest exponent possible. 

NOTE: The $octin DBX variable changes the default to octal. The $hexin 
variable changes the default to hexadecimal. See Predefined DBX Variables. 



Output Constant 


Constant 


Description 


default 


decimal 
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NOTE: The $octints DBX variable changes the default to octal. The $hexints 
variable changes the default to hexadecimal. See Predefined DBX Variables. 



( 



Basic DBX Commands 



DBX offers many commands; however, for most debugging sessions, you need 
to use only those shown in the next table. 



Common Debugging Commands 


Command 


Select this command to. n 


/REGEX 


Search ahead in your source file for a specific string 


?REGEX 


Search back in your source file for a specific string. 


continue 


Continue executing your program. 


down [EXP] 


Move down the activation levels of the stack. 


dump 


Get all information that DBX has about a 
procedure. 


func PROCEDURE 


Select the procedure you want to look at. 


list 


Look at the 10 lines preceding and fol- 
lowing the current line. 


list EXP 


Look at line specified by EXP. 


print EXP 


Print the value of any variable. 


quit 


End the debugging session. 


run 


Run the program being debugged. 


rerun 


Run the program again with the same 
arguments you specified to the run 
command. 


step [EXP] 


Step the specified number of lines, 


stop at LINE 


Stop at specified line in the source. 


stop in PROCEDURE 


Set a breakpoint at the beginning of a 
a procedure. 


up [EXP] 


Move up the activation levels of the stack. 


whprp 


Do a stack trace to see what procedures 


W11C1 c 


are currently active. 



Working with the DBX Monitor 

This part of Chapter 5 covers these topics: 

• the history feature 

• DBX command line editing 

• typing of multiple commands 



c 
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• DBX completion of program symbol names 
Using History (history & ! commands) 

The DBX history feature is similar to the C shell's history feature; however, 
DBX history doesn't work in the middle of the line or with !$. It works only at 
the beginning of the line. 

You can set the number of history lines using the $lines variable. The default is 
20. To reset this variable, use the set command. See Setting DBX Variables. 

To see a list of the commands in your history list, type the history (alias h) 
command. To repeat a previous command, use one of the exclamation point (!) 
commands. 

Syntax: 



Command 


Select this command to- 


history 

! string 
! INT 

!-INT 


Print the items in your history list. 

Repeat the most recent command that starts with 
the specified string. 

Repeat the command associated with the specified 
integer. 

Repeat the command that occurred the specified 
integer before #ie most recent command. 



Example: 



(dbx) history 

10 print x 

11 print y 

12 print z 
(dbx) !12 
(!12 = printz) 
123 

(dbx) 



Editing on the DBX Command Line 



DBX provides commands that permit you to edit the command line. These 
commands make it possible for you to correct mistakes without having to retype 
an entire command. See the UNIX Programmer' $ Manual page lsh(l) for a full 
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description of the editing commands. Here are the ones that you'll most com- 
monly use: 



c 



DBX Command Line Editing 



Command 



carriage return 



A B 

A D 

A E 

A H ,DELETE 

A N 
Ap 



Select this command to.., 



Repeat the last command you issued to 
DBX. You can turn this feature off by 
setting the $repeatmode variable to 0. 
See Setting DBX Variables. 

Move the cursor to the beginning of the 
command line. 

Move the cursor back one character. 

Delete the character at the cursor. 

Move the cursor to the end of the line. 

Move the cursor ahead one character. 

Delete the character immediately preceding 
the cursor. 

Move ahead one line. (This line comes from 
the history list.) 

Move back one line. (This line comes from 
the history list.) 



c 



NOTE: In the above table, the notation A represents the CTRL key. For ex- 
ample A A is the same as pressing the CTRL and A keys. 

Typing Multiple Commands 

By using a semicolon (;) as a separator, you can type multiple commands on the 
same command line. This can be useful when you use the when command. 
See Writing Conditional Code in DBX (when). 

Syntax: 



Command 


Select this command to.*. 


COMMAND; COMMAND 


Type multiple commands on the same 
line. 
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Example: 



(dbx) stop at . 


58; rerun 










[1] 


stop at 


58 


"sam.c":58 










[1] 


stopped 


at 


[Printline 


58, 


0x2f8] 


pline- 


->string 


(dbx) 















Completing Program Symbol Names 



When you want to save typing or when you don't remember a symbol's full 
name, DBX can complete the name for you. If DBX finds a unique completion, 
it adds the completion to the input line; otherwise, it lists all possible comple- 
tions and lets you choose the appropriate one. 

To use this feature, type the first part of the name and press A Z. 

Syntax: 



Command 


Select this command to... 


STRINGS 


Complete a symbol name or to see what symbol 
names contain the specified string. 



Example: 



(dbx) i A z 

ioctl.ioctl . ioctl isatty . isatty . isatty i int 

(dbx) i A 



the list of all symbols 
that begin with i in the 
program 



NOTE: You'll often see things that are data types and library symbols. 



(dbx) print file A z 

(dbx) print f ile__header_ptr 

0xl24ac 

(dbx) 



ler 

t 



dbx completes the 
symbol name for you 
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Controlling DBX 

This part of Chapter 5 covers these topics: 

• how to set and unset DBX variables 

• the predefined DBX variables 

• how to create and remove command aliases 

• the predefined DBX aliases 

• how to record and play back input and output 

• how to invoke a shell from DBX 

• how to check and delete DBX status items 
Setting DBX Variables (set) 

The set command defines a DBX variable, sets an existing DBX variable to a 
different type, or displays a list of existing DBX predefined variables. 

You cannot define a debugger variable that has the same name as a program 
variable. You can see the setting for a single variable by using the print com- 
mand. The DBX predefined variables are listed Table 5.2 in the section 
Predefined DBX Variables. 

Syntax: 



( 



c 



Command 


Select this command to,.. 


set 

set VAR « EXP 


Display a list of DBX predefined 
variables. 

Assign a new value to a variable 
or to define a new variable. 



( 
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Example: 



(dbx) set 






$listwindow 


i n ^ 




1U ^* 


"'""" old value 


$datacache 


i 




$main "main" 




$pagewindow 


22 




$page 


1 




$maxstrlen 


128 




$cursrcline 


24 




more (no?) no 






(dbx) set $listwindow - 15 




(dbx) set 






$listwindow 


i c , ^ 




-L u ^^ 


new value 


$datacache 


1 




$main "main" 




$pagewindow 


22 




$page 


1 




$maxstrlen 


128 




$cursrcline 


24 




more (no?) no 






(dbx) 







Removing Variables (unset) 



Use the unset command to remove the specified DBX variable from the list. To 
see a full list of DBX variables, use the set command or see Predefined DBX 
Variables. 

Syntax: 



Command 


Select this command to... 


unset VAR 


Unset the value of a DBX variable. 
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Example: 



(dbx) set test = 5 




(dbx) set 






$listwindow 


10 




$datacache 


1 




$main 


"main" 




$pagewindow 


22 




$test 


b ** ■ ' ' 


™— new variable 


$maxstrlen 


128 


on list 


$cursrcline 


24 




more (no?) no 




(dbx) unset 


$page 




(dbx) set 






$listwindow 


15 




$datacache 


1 




$main 


"main" 




$pagewindow 


22 




$maxstrlen 


128 ^«— ™-— 


new variable 


$cursrcline 


24 


removed from 


more (no?) no 


list 


(dbx) 







c 



Predefined DBX Variables 



The predefined DBX variables are listed in Table 5.2 starting on the next page, 
The variables that are preset, but which you can change, are indicated by I, B, 
and S notations in the Key column, Variables that only DBX can set, but are 
available to you for information, are indicated by an R; the table below sum- 
marizes the notations in the Key column. 



( 



Key 


Description 


I 
B 

S 
R 


integer 

boolean 

ASCII character string 

reset exclusively and 

periodically by the debugger 



( 
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Debugger Variables 



Key 



Variable 



Default 



Description 



B 



SR 



SR 



Saddrfrmt 



$casesense 



IR 


$curevent 


IR 


$curline 


IR 


$cur$rcline 




$curpc 


B 


$datacache 



$debugflag 
$defaultout 

$defaultin 



$defin 

$defout 

$dispix 



"Ox%x" 



none 



none 



none 



Specifies the format for addresses. 
You can set this to anything you 
can format with a C language 
printf statement. 

Specifies whether source 
searching and variables are case 
sensitive. A nonzero value means 
case sensitive; a means not case 
sensitive. 

Shows the last event number 
as seen in the status feature. 

Shows the current line in the 
source code. 

Shows the last line you listed 
plus 1. 

Shows the current address. Used 
with the wi and li aliases. 

Caches information from the data 
space so that DBX only has to 
check the data space once. If 
you're debugging the operating 
system, you need to set this 
variable to 0; otherwise, set it 
to a nonzero value. 

An internal debug flag used 
to debug DBX. 

Shows the name of the file that 
DBX uses to store information 
when you set the record output 
command. 

Shows the name of the file that 
DBX uses to store information 
when you set the record input 
command. 

Used internally by dbx. 



Table 52 (1 of 3). Predefined DBX Variables. 
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Debugger Variables 


Key 


Variable 


Default 


Description 


B 


$hexchars 





Displays hexadecimal when set to a 
non-zero value. Hexadecimal 
overrides octal. 


B 


$hexin 





Changes the default input constants 
to hexadecimal when set to a non- 
zero value. 


B 


$hexints 





Changes the default output constants 
to hexadecimal when set to a non- 
zero value. Hexadecimal over- 
rides octal. 


B 


$hexstrings 





Specifies whether you want to see 
all strings printed in hexadecimal. 
A 1 means use hexadecimal; a 
means use characters. 


IR 


$historyevent 


none 


Shows the current history number. 


I 


$lines 


20 


Specifies the size of your DBX 
history list. 


I 


SUstwindow 


10 


Specifies how many lines the 
list command lists. 


S 


$main 


"main" 


Specifies the name of the procedure 
where execution is to begin, DBX 
by default starts at the procedure main 
unless you specify otherwise. 


I 


$maxstrlen 


128 


Specifies how many characters 
of a string that DBX will 
print for pointers to strings. 


B 


$octints 





Changes the default output constants 
to octal when set to a non-zero 
value, Hexadecimal overrides 
octal. 


B 


$octin 





Changes the default input constants 
to octal when set to a non-zero 
value. Hexadecimal overrides octal. 


B 


$page 


1 


Specifies whether to page long 
information. A nonzero value 
turns on paging; a turns it 
off. 



c 



( 



Table 5.2 (2 of 3). Predefined DBX Variables. 



( 
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Debugger Variables 


Key 


Variable 


Default 


Description 


I 


$pagewindow 


22 


Specifies how many lines you see 
when you look at information 
that runs longer than one screen. 
Change this variable to match the 
number of lines on your terminal. 
If you set this variable to 0, it 
assumes a minimum of one line. 


B 


$pimode 





Prints input when you use the 
playback input command. 


B 


$printdata 





Specifies whether to print the 
value of the registers where 
you disassemble instructions. A 
nonzero value means print the 
register value; a means don't 
print the value. 


B 


Sprintwide 





Specifies whether you want to 
print variable values (for 
example, structures or arrays) in 
vertical or wide format. Anon- 
zero value means wide format; 
a means vertical format. 


S 


$prompt 


"(dbx)" 


Sets the prompt for DBX. 


B 


$regstyle 


1 


Specifies the type of register 
names to be used. A value of 
1 specifies hardware names; a 
specifies software names as 
defined by the file regdefs.h. 
This variable does not affect 
coprocessor register names. 


B 


$repeatmode 


1 


Specifies whether you want DBX 
to repeat the last command when 
you press the carriage return, A 
nonzero value means repeat the 
last command; a means don't 
repeat the last command. 


B 


$romode 





Records input when you use the 
record output command. 



Table 52 (3 of 3). Predefined DBX Variables, 
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Creating Command Aliases (alias) 



Use the alias command to see a list of all current aliases or to define a new 
alias. 

DBX lets you create an alias for any debugger command. Enclose multi-word 
command names within double or single quotation marks. You can also define 
a macro as part of an alias, as shown in the example in this section. 

DBX has a group of predefined aliases, which you can modify or delete; you 
can also add your own aliases You can include all aliases in the Jhxinit file if 
you want to use them in future debugging sections. 

For a complete list of predefined aliases, see Predefined DBX Aliases., 

Syntax: 



Command 


Select this command to... 


alias 

alias NAME! [ (ARG1 „ .ARGN) 3 "NAME2" 


See a list of all existing 
aliases. 

Define a new alias, NAME1 
specifies the alias. NAME2 
specifies the command. ARG1 
...ARGN let you specify 
arguments to the alias. 



c 



Example: 



( 



(dbx) alias ok(x) "stop at x" 

(dbx) ok(58) 

[1] Stop at .58 "sam-c" < ■■ ■ 

(dbx) 



breakpoint set at 
line 58 



Removing Command Aliases (unalias) 



The unalias command removes an alias from a command. You must specify 
the alias you want to remove; otherwise, you get a syntax error. This effect 
lasts only for the current debugging session. For a full list of predefined DBX 
aliases, see Predefined DBX Aliases. 

Syntax: 



Command 


Select this command to... 


unalias "name" 


Remove an alias from a command, 
where name is the alias name. 



( 
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Example: 



(dbx) 


alias 




h 


history 




si 


stepi 




Si 


nexti 




ni 


nexti 




pi 


playback input 




ro 


record output 




ri 


record input 




a 


assign 




t 


where 




J 


status 




bp 


stop in 




b 


stop at 




g 


goto 




s 


step 




More 
(dbx) 


(n if no) ?n 


the user decides to unalias h from 


(dbx) 


alias 


history and it disappears from the 


si 


stepi 


list 


Si 


nexti 




ni 


nexti 




pi 


playback input 




ro 


record output 




ri 


record input 




a 


assign 




t 


where 




J 


status 




bp 


stop in 




b 


stop at 




g 


goto 




s 


step 




More 


(n if no) ?n 




(dbx 


) 





Predefined DBX Aliases 



To list current aliases, use the alias command. You can override any predefined 
alias by redefining it with the alias command or by removing it from the list 
with the unalias command. The tables on the following pages shows the 
debugger predefined aliases. 



Languages Programmer's Guide 



5-23 



Chapter 5 



Debugger Aliases 


Alias 


Command 


Select this alias to... 


? 


help 


Print a list of all DBX commands. 


a 


assign 


Assign a value to a program variable. 


b 


stop at 


Set a breakpoint at a specified line. 


bp 


stop in 


Stop in a specified procedure. 


c 


continue 


Continue program execution after a 
breakpoint. 


d 


delete 


Delete the specified item from the 
status list 


e 


file 


Look at the specified source file. 


f 


func 


Move to the specified activation level 
on the stack. 


g 


goto 


Go to the specified line and begin 
executing the program there. 


h 


history 


List all items currently on your history 
list 


J 


status 


See what items are on your status 
list 


1 


list 


List the next 10 lines of source code. 


nor S 


next 


Step over the specified number of 
lines without stepping into procedure 
calls. 


nior 
Si 


nexti 


Step over the specified number 

of assembly code instructions without 

stepping into procedure calls. 


P 


print 


Print the value of the specified 
expression or variable, 


pd 


printf'%d\n" 


Print the value of the specified 
expression or variable in decimal. 



( 



w'"""*»np 
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Debuj 


»ger Aliases 


Alias 


Command 


Select this alias to— 


Pi 


playback input 


Replay DBX commands that you saved 
with the record input command. 


po 


printf"%o\n" 


Print the value of the specified 
expression or variable in octal. 


pr 


printregs 


Print values for all registers. 


px 


printf"%x\n" 


Print the value of the specified 
variable or expression in hexadecimal. 


q 


quit 


End your debugging session. 


r 


rerun 


Run your program again with the same 
arguments that you specified with the 
runcommand. 


ri 


record input 


Record every command you type in 
a file. 


ro 


record output 


Record all debugger output in the 
specified file. 


s 


step 


Step the next number of specified 
lines. 


si 


stepi 


Step the next number of specified lines 
of assembly code instructions. 


t 


where 


Do a stack trace. 


u 


list$curline-15:10 


List the previous 10 lines. 


w 


list $curline-5:10 


List the 5 lines preceding and 
following the current line. 


W 


list $curline-10:20 


List the 10 lines preceding and 
following the current line. 


wi 




List the 5 machine instructions preceding 
and following the machine instruction. 



Recording Input (record input) 



Use the record input command to record your debugger input. This command 
provides an excellent means for creating a command file. You can use record 
input with the source or playback input commands to repeat a sequence of 
command multiple times. See Playing Back the Input. 

The syntax of record input is shown below. 
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Syntax: 



Command 


Select this command to.** 


record input [filename] 


Record everything you type to DBX 
in a file, 



DBX saves the recorded input in filename. If you omit filename, DBX saves 
the recorded input in a temporary file, which is deleted at the end of the DBX 
session. The name of the temporary file is in the system variable $defaultin: 
you can display the temporary filename using the print command as follows: 

print $defaultin 

Use the temporary file to repeat previously executed DBX commands only in 
the current debugging session; specify filename to create a command file for use 
in subsequent DBX sessions, You can see whether you've set record input by 
issuing the status command. Use the delete command to stop record input. 

Example; 



(dbx) record input 

[2] record input /tmp/dbxt0013516 (0 lines). 

(dbx) status 

[1] record input /tmp/dbxt 0013516 (0 lines) 

(dbx) stop in printline 

[2] stop in printline 

(dbx) when i **' 19 {stop} 

[3] traceif i - 19 {stop } 

(dbx) 



The following is recorded in the temporary file after executing the above com- 
mands: 



c 



status 

stop in printline 

when i - 19 {stop} 



Recording Output (record output) 



Use the record output command to record DBX output during your debugging 
session. For example, you might want to use this command when you have a 
large array that doesn't fit the screen, You can record the information in a file 
and look at it later. If you want to record your input as well, set the DBX vaiv 
Me$rimode. Use the playback output command to look at the recorded in- 
formation, or use any UNIX system editor. 



( 
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Syntax: 



Command 


Select this command to... 


record output [filename] 


Record all DBX output in a file. 



DBX saves the recorded output in filename. If you omit filename, DBX saves 
the recorded output in a temporary file, which is deleted at the end of the DBX 
session. The name of the temporary file is in the system variable $defaultout\ 
you can display the temporary filename using the print command as follows: 

print $defaultout 

Use the temporary file when you need to refer to the saved output only during 
the current debugging session; specify filename to save information required 
after exiting the current debugging session. 

You can see whether you've set record output by issuing the status command. 
Use the delete command to stop record output. 

Example: 



(dbx) record output code 






filename 




[3] record output code 


(0 


line 


s) 


(dbx) stop at 25 








[4] stop at "sam.c":25 








(dbx) run sam.c 








[4] stopped at [main: 25 


,8xlb0] 


if (i<2) { 


(dbx) 









Output: 

The above example writes the following output in the file code: 



[3] record output code (0 lines) 

(dbx) [4] stop at ''sam.c" :25 

(dbx) [4] stopped at [main:25, Qx21b0] if 



(i<2) { 



Playing Back the Input (source or playback input) 



Use these commands to replay the commands that you recorded with the record 
input command. If you don't specify a filename, DBX uses the current tempo- 
rary file that it created for the record input command. If you set the DBX 
variable Spimode to 1, the commands are printed out as they are played back. 
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Syntax: 



Command 


Select this command to.,. 


playback input [filename] 
source [FILE] 


Execute the commands from the 
specified file. 



c 



Example: 



(dbx) playback input 

status 

[1] record input /tmp/dbxt0013516 

[2] stop in Printline 

[3] traceif i « 19 {stop} 

stop in printline 

[4] stop in Printline 

when i * 19 {stop} 

[5] traceif i~19 {stop } 

(dbx) 



(1 lines) 



Playing Back the Output (playback output) 



This command displays output saved with the record output command. The 
playback output command works the same as the UNIX system cat command. 
If you don't specify filename, DBX uses the current temporary file created for 
the record output command, 

Syntax: 



c 



Command 


Select this command to... 


playback output [filename] 


Print the commands from the 
specified file, 



Example: 



(dbx) playback outputQ^ ode^ 1 ^ ' " the file name 

[3] record output code^TFTLines) 

(dbx) [4] stop at "sam.c":25 

(dbx) [4] stopped at [main; 25, OxlbO] 

(dbx) 



t 



if (i<2){ 



the contents of 
the file 
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Invoking a Shell from DBX (sh) 



To invoke a sub-shell, type sh at the DBX prompt, or type sh and a shell com- 
mand at the DBX prompt. If you invoke a sub-shell, type exit or press A D to 
return to DBX. 

Syntax: 



Command 


Select this command to*.. 


sh 

sh [SHELL COMMAND] 


Call a shell from DBX. 
Execute the shell command. 



Example: 



(dbx) sh 

% ^ 

% date 

Tue Apr 8 17:25:15 PST 1986 

% exit 

(dbx) sh date 

Tue Apr 8 17:29:34 PST 1986 

(dbx) 



calls a shell 



executes the 
shell date 
command 



Checking the Status (status) 



Use the status command to check which, if any, of these commands you cur- 
rently have set: 

• stop or stopi commands for breakpoints 

• trace or tracei commands for line-by-line variable tracing 

• when command 

• record input and record output commands for saving informa- 
tion in a file 

Syntax: 



Command 


Select this command to... 


status 


Check the status of commands. 
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Example: 



(dbx) status 

[4] trace i in printline 

[3] print pline A at "sam.c":58 

[2] stop in Printline 

[1] record output /tmp/dbxt0018898 (0 lines) 

(dbx) 



the status 
item number 



c 



Deleting Status Items (delete) 

Use the delete command to remove items from the status list. 
Syntax: 



Command 


Select this command to... 


delete EXP1, . . .EXPN 
delete all 


Delete the specified status item (EXP) 
from the status list 

Delete all status items. 



c 



Example: 



;58 



(dbx) status 

[4] trace i in printline 

[3] print pline A at "sam.c' 

[2] stop in printline 

[1] record output /tmp/dbxt0018898 (0 lines) 

(dbx) delete 4 

(dbx) status 

[3] print pline at "sam.c":58 

[2] stop in printline 

[1] record output /tmp/db*t 0018 890 (0 lines) 

(dbx) 



f 



the status 
item number 
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Examining Source Programs 



This section describes how to list and edit source programs while using DBX; it 
gives details on the DBX commands that allow you to do the following: 

specify source directories 

move to a procedure 

change source files 

list your source code 

search for strings in your source code 

call an editor from DBX 

print symbol names 



print type declarations for variables 

Specifying Source Directories (use) 



Unless you specified the -I option at invocation, DBX looks for source files in 
the current directory or in the object file's directory. The use command lets you 
change the directory and list the directories currently in use. The command rec- 
ognizes absolute and relative pathnames (for example, ./); however, it doesn't 
recognize the C shell tilde (~) syntax — for example, ~john/src. 

Syntax: 



Command 


Select this command to... 


use 

use DIR1 . . . DIRN 


List the current directories. 
Specify different directories. 



Example: 



(dbx) use 



(dbx) use /usr/local/lib 
(dbx) use 

/usr/local/lib ,^ 

(dbx) 



current directory 



new directory 



Moving to a Specified Procedure (tunc) 



The func command moves you up or down the activation stack, as appropriate. 
The function can be a procedure name or an activation level number. To find 
the name or activation number for a specific procedure, do a stack trace with the 
where command. You can also move through the activation stack by using the 
up and down commands. For a definition of activation levels, see What Are 
Activation Levels? 
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The func command changes the current line, the current file, and the current 
procedure. This changes the scope of the variables you can access. You can 
use the func command when a program isn't executing— for example, when 
you want only to examine source code. 

Syntax: 



c 



Command 


Select this command to... 


func 

func PROCEDURE 

func EXP 


Print the current activation levels. 

Move to the activation level 
specified by the procedure name. 

Move to the activation level specified 
by the expression. 



Example: 



(dbx) where 

> Printline [pline =* 0x7f££5b80) [ vv sam. c* :58, 0x2f 7] 
1 $blockl [ xx sam.c":47, 0x2bb] 



n(argc-2, argv=*0x7ff febaO) ["sam. c" : 47, 0x2bb] 
A 

prir tline (&linel) 



func 2 
7 



inc main 



2 maj 

(4bx) 

in 4 
(cbx)f 

(qbx) 

the proce- the procedure's 
dure name arguments 

the activation 
level 



t 



the source 
file name 



t 



the current 

program counter 
the current 
line 



( 



Specifying Source Files (file) 



The file command changes the current source file to a file you specify. The 
new file becomes the current file, which you can search, list, and perform other 
operations on. 

CAUTION: Before setting a breakpoint or trace, use the func command to get 
the correct procedure, because the file command cannot be specific enough for 
the debugger to access the information necessary to set a breakpoint. 



( 
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Syntax: 



Command 


Select this command to... 


file 
file FILE 


Print the name of the file you're 
currently using. 

Change the current file to the specified 
file. 



Example: 



(dbx) file 

sam.c :*n — — 

(dbx) file data.c 
(dbx) file 

data.c -^1 " — ! 

(dbx) 



current file 



new file 



Listing Your Source Code (list) 



The list command displays lines of source code. The DBX variable $listwindow 
defines the number of lines DBX lists by default. The list command uses the 
current file, procedure, and line unless otherwise specified. It moves the current 
line forward. 

Syntax: 



Command 


Select this command to... 


list 

list EXP 
list EXP: INT 

list procedure 


List lines for $listwindow lines starting 
at the current line. 

List the specified line. 

List the specified number of 

lines (INT), starting at the specified 

line (EXP). 

List the specified procedure for 
$listwindow lines. 



For example: 



(dbx) list 53:2 
53 



54 LINETYPE *pline; 



(dbx) 



the user specified 
a list starting at 
line 53 for two lines 
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If you use the predefined alias w, (see Predefined DBX Aliases), you get some- 
thing like this: 



( 



(dbx) 


w 
53 
54 
55 
56 


LINETYFE *pline; 
{ 








>* 
(dbx' 


57 
58 

_5.a_ 

60 


fprintf (stdio, #53d. 
pi "in^-^.st-r'incr; ^— „,.._.„ 


(%d)%s" 


f pl. 


Lne->linenumber 
current line 


„ff_,:isj„(st.doii_tL; 

} /* Printline */ 













NOTE: > shows the current line and * shows the location of the program 
counter (pc) at this activation level. 



Searching Through the Code (/ and ?) 



The / and ? commands search for regular expressions in source code. The slash 
(/) searches forward; the question mark (?) searches back from the current line. 
Both commands wrap around the end of the file if necessary, searching the en- 
tire file, from the point of invocation back to the same point. If you set the 
DBX variable $casesense on, DBX distinguishes upper-case letters from lower- 
case. 

Syntax: 



( 



Command 


Select this command to... 


/REGEX 
7REGEX 


Search ahead in the code for the 
specified regular expression. 

Search back in the code for the 
specified regular expression. 



Example: 



(dbx) 


/lines 














cont 


inue ; 


/*don 


't 


count 


blank 


lines 


*/ 


(dbx) 


/lines 














linel .length- 


=i 












(dbx) 
















continue; 


/*don' 


t 


count 


blank 


lines 


*/ 


(dbx) 

















Calling an Editor from DBX (edit) 



The edit command lets you make changes to your source code from within 
DBX. For the changes to become effective, you must exit DBX, recompile 
your program, and, if you want to continue debugging, restart DBX. 



( 
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Syntax: 



Command 


Select this command to.,. 


edit 

edit [filename] 


Call an editor from DBX on the 
current file. 

Call an editor and edit the specified 
file. 



The edit command loads the editor that you set as an environment variable 
EDITOR. If you don't set the environment variable, DBX assumes the vi edi- 
tor. When you exit the editor, it returns you to the DBX prompt. 



Printing Symbolic Names (which and whereis) 



The which and whereis commands print program variables as described below. 
These commands are useful for programs that have multiple variables with the 
same name, occurring in different scopes. The commands follow the rules de~ 
scribed in the section Qualifying Variable Names. 

Syntax: 



Command 


Select this command to,.. 


which VAR 
whereis VAR 


Print the default version of the 
variable. 

Print all versions of the specified 
variable. 



Example: 



(dbx) 


which i 




















sam.main. 1 




















(dbx) 


whereis 


i 


















sam.p. 


rintline 


1 


sam 


.mam 


.$blo 


ckl 


i 


sam 


mam 


i 


(dbx) 























Printing Type Declarations (whatis) 

The whatis command lists the type declaration for variables and procedures in 
your program. 

Syntax: 



Command 


Select this command to... 


whatis VAR 


Print the type declaration for the 
specified variable or procedure in 
your program. 
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Example: 



(dbx) what is main 

int main (argc, argv) 

int argc; 

unsigned char **argv; 

(dbx) whatis i 

int i; 

(dbx) 



( 



Coffin 



The commands in this section control program execution by performing the fol- 
lowing functions; 

• run and rerun a program 

• step through a program one line at a time 

• return from a procedure call 

• start at a specified line 

• continue after a breakpoint 

• assign values to program variables 

These functions are described in detail in the sections that follow. 



( 



Running Your Program (run and rerun) 



The run or rerun starts program execution. You can specify arguments to 
either command. Arguments to these commands override previous arguments; 
however, if you don't specify arguments to the rerun command, it uses the last 
set of arguments. If you don't specify arguments to the run command, it runs 
the program without arguments. 

These commands can be used to redirect program input and output. This fea- 
ture works like redirection in the C shell. The optional parameter < FILE1 redi- 
rects input to your program from the specified file. >FILE2 redirects output 
from the program to the specified file. The optional parameter >&FILE2 redi- 
rects stderr and stdout output to the specified file, 

NOTE: This output differs from the output you save with the record output 
command. That command saves debugger (not program) output in a file. See 
Recording the Output (record output). 



( 
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Syntax: 



Command 


Select this command to... 


run [ARG1, . . .ARGN] [<FILE1] [>FJLE2] 
run [ARG1, . . .ARGN] [<FILE1] [>&FILE2] 

rerun [ARG1 . . .ARGN] [<FILE1] [>FILE2] 
rerun [ARG1. , .ARGN] [<FILE1] [>&FILE2] 


Run your program with 
the specified arguments. 

Rerun your program with 
the arguments you specified 
to therun command or with 
new arguments. 



The arguments to the run command specify any program arguments that your 
program might have. 

Example: 



(dbx) rx, 

0. (19)1 

1. (14) 

2. (22) 

* n • 


in "nm c ^tf 




the argument 


is sam.c 


■inclucie<stclio.h> 
struct line { 
char string [256] ; 



Example: 



(dbx) rerun 
. ( 19 ) #include<stdio . h> 

1. (14) struct line { 

2. (22) char string[256] ; 



program terminated normally 
(dbx) 



Executing Single Lines of Your Code (step and next) 



The step and next commands execute a fixed number of source code lines as 
specified by EXP. If you don't specify EXP for step and next, DBX executes 
one source code line. If you specify EXP, DBX executes the source code lines 
as follows: 

• For step and next, DBX does r^ot take comment lines into con- 
sideration in interpreting EXP, The program executes EXP 
source code lines, regardless of the number of comment lines 
interspersed among them. 

• For step, DBX considers EXP to apply to both the current pro- 
cedure and to called procedures. The program stops after exe- 
cuting EXP source lines in the current procedure and any called 
procedures. 
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• For next, DBX considers EXP to apply to only the current pro- 
cedure. The program stops after executing EXP source lines in 
the current procedure, regardless of the number of source lines 
executed in any called procedures. 

Use step and next to execute source lines after a breakpoint. 
Syntax: 



c 



Command 


Select this command to... 


step [EXP] * 
next [EXP] * 


Execute the specified number of lines of source 
code. EXP refers to the number of lines to be 
executed in both the current procedure and any 
called procedures. 

Execute the specified number of lines of source 
code. EXP refers to the number of lines to be 
executed in only the current procedure, regard- 
less of any called procedures executed. 


*Defaultisl. 



Example: 



(cibx) rerun 

[3] stopped at [printline:58, 0x2f 8] pline^>string) ; 

(dbx) step 2 

(19) #include <stdio.h> 

[$blockl:48 r 0x2bc] } /*while*/ 

(dbx) step 

[$blockl : 41, 0x260] i^strlen (linel . string) ; 

(dbx) A 



$blockl gets created 
because it defines the 
scope for its own local 
variables 



c 



Returning from a Procedure Call (return) 



The return command is for use in a called procedure when stepping through 
the code one instruction at a time. The command causes the remaining instruc- 
tions in the procedure to be executed and the program to stop at the first instruc- 
tion on return from that procedure. 



c 
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Syntax: 



Command 


Select this command to... 


return 

return PROCEDURE 


Execute the current procedure and return 
to the next sequential line in the calling 
procedure. 

Execute the program until DBX returns 
to the specified procedure. 



Example: 



(dbx) rerun 

[6] stopped at [printline: 58, 0x2f8] pline->string) 

(dbx) return 

(19) #include <stdio.h> 

stopped at [$blockl : 48, 0x2bc] } /*while*7 

(dbx) 



Starting at a Specified Line (goto) 



The goto command shifts program execution to a line you specify. This com- 
mand is useful in a when statement — for example, to skip a line that you know 
has problems. 

Syntax: 



Command 


Select this command to... 


goto LINE 


Go to a specified line and continue 
execution. 



Example: 



(dbx) when at 58 {goto 43} 

[1] start "sam.c" :48 at "sam.c' 

(dbx) 



:58 



Continuing after a Breakpoint (cont) 



The cont command resumes program execution after a breakpoint. The cont to 
and cont in are in effect at the time you issue them; when your program again 
reaches a breakpoint, you can reissue either cont to or cont in to continue, if 
desired. If SIGNAL is specified as a parameter (see below), DBX sends the 
specified signal to the program and continues. 
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Syntax: 



Command 


Select this command to... 


cont 


Continue from the current line. 


cont to LINE 


Continue until the specified line. 


cont in PROCEDURE 


Continue until the specified procedure. 


cont SIGNAL 


Continue from the current line and 
send the signal. 


cont SIGNAL to LINE 


Continue until reaching the specified 
line and send the signal. 


cont SIGNAL in PROCEDURE 


Continue until reaching the specified 
procedure and send the signal. 



c 



Example; 



(dbx) stop in Printline 












[1] stop in 


Printline 












(dbx) rerun 














[1] stopped 


at [printline: 


58, 


0x2f8] 


pline- 


->string) ; 


(dbx) cont 














(19)#include <stdio.h> 










[1] stopped 


at [printline: 


58, 


0x2f8] 


pline 


->st 


ring) ; 


(dbx) 















Assigning Values to Program Variables (assign) 

The assign command changes the value of existing program variables. 
Syntax: 



Command 


Select this command to,.. 


assign EXP1 == EXP2 


Assign a new value to a program 
variable. 



Example: 



c 



(dbx) print i 
19**— ~~ 



(dbx) assign i - 10 
10-* — — 



' the value of i 



— the new value of i 

(dbx) assign * ($integer*) 0x455 *= 1 «*H 



(dbx) 



coerce the 
address to be 
an integer 
and assign a 
Itoit 



( 
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Setting Breakpoints 



Overview 



A breakpoint stops program execution and lets you examine the program's state 
at that point. This part of Chapter 5 shows you how to do the following: 

• set breakpoints at lines 

• set breakpoints in procedures 

• continue running your program after a breakpoint 

• stop for signals 



When a program stops at a breakpoint, the debugger displays an informational 
message. For example, if you set a breakpoint in the sample program sam.c 
(see Sample Program at the end of the chapter) at line 23 in the main proce- 
dure, you get this message: 



[2] stopped at [ main:23, Oxlcc] if (argc < 2) { 

(dbx) AAA 

A 



breakpoint 
status number 



t 



line 
number 



procedure 
name 



""" source 

line 

the current 
program counter 
(use this number 
to print the assembly 
language instructions from 
this point (see Debugging at 
the Machine Level). 



Before setting a breakpoint in a program that has multiple files, be sure that 
you're setting the breakpoint in the right file. 

To select the right procedure, follow these steps: 

1. Use the ftmc command and specify a procedure name. This command 
moves you to the file that contains the specified procedure. See Control- 
ling Your Program. 

2. List the lines of the procedure. Use the list command. See Controlling 
Your Program. 

3. When you see the procedure or line you want, use a stop command to set a 
breakpoint. 



Setting Breakpoints at Lines (stop at) 



The stop at command sets a breakpoint at a specific line. DBX stops only at 
lines that have executable code. If you specify an unexecutable line, DBX sets 
the breakpoint at the next executable line. If you specify the VAR parameter, 
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the debugger prints the variable and stops only when VAR changes; if you spec- 
ify if EXP, DBX stops only when EXP is true. 

Syntax: 



( 



Command 


Select this command to... 


stop [VAR] at 


Stop at the current line. 


Stop [VAR] at LINE 


Stop at a specified line. 


stop [VAR] at LINE 
if EXP 


Stop at a specified line only if 
the expression is true. 



NOTE: if EXP is checked before VAR. 
Example: 



(dbx) stop at 58 

[16] stop at "sam.c":58 

(dbx) rerun 

[16] stopped at [printline:58 f 0x2f 8] pline->string) ; 

«*>*> k k k 



the 

procedure 

name 



the line 
number 



the current 
program counter 



( 



Setting Breakpoints in Procedures (stop in) 

The stop in command sets a breakpoint at the beginning or, conditionally, for 
the duration of a procedure. 

Syntax: 



Command 


Select this command to... 


stop in PROCEDURE 


Stop at the beginning of the procedure. 


stop VAR in PROCEDURE 


Stop in the specified procedure when 
VAR changes. 


stop in PROCEDURE if EXP* 


Stop in the specified procedure if EXP 
is true, 


stop VAR in PROCEDURE 
if EXP* 


Stop in the specified procedure when 
VAR changes and EXP is true. 


*EXP is checked before VAR. 



NOTE: Specifying both VAR and EXP causes stops anywhere in the proce- 
dure, not just at the beginning, Using this feature is expensive, because the 
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debugger must check the condition before and after each source line is exe- 
cuted. 



Example: 



(dbx) stop in Printline 

[15] stop in Printline 

(dbx) rerun 

[15] stopped at [printline: 58, 02f 8] pline->string) ; 

(dbx) 



| | A 

I the line I 



the line 
number 

the 

procedure 

name 



the current 
program counter 



Setting Conditional Breakpoints (stop if) 



The stop if command causes DBX to stop program execution upon encounter- 
ing a condition you specify. Because DBX must check after the execution of 
each line, this command is expensive and slows program execution markedly. 
Whenever possible, use stop at or stop in instead of stop if. 

Syntax: 



Command 


Select this command to... 


stop if EXP 
stop VAR if EXP 


Stop if EXP is true. 

Stop if VAR changes and EXP is 
true. 


EXP is checked before VAR! 



NOTE: EXP is checked before VAR. 
Tracing Variables (trace) 



The trace commands list the value of a variable during program execution as 
well as determine the scope for the variables that you're tracing. 
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Syntax: 



( 



Command 


Select this command to... 


trace VAR 


List the specified variable after 
each source line is executed. 


trace VAR at LINE 


List the specified variable at the 
specified line, 


trace VAR in PROCEDURE 


List the specified variable in the 
specified procedure. 


trace VAR at LINE if EXP 


List the variable at the specified 
line when the expressions is true. 


trace VAR in PROCEDURE if EXP 


List the variable in the specified 
procedure when the expression 
is true. 



NOTE: EXP is checked before VAR. 
Example: 



(dbx) 


trace i 








[15] 


trace i in $blockl 








(dbx) 


rerun 








[Printline ;58 f 0x2f 8] :i=19 








[23] 


[Printline : 58 , 0x2f 8] 


pline->stri 


ng) ; 


( 


19) #include<stdio.h> 






[25] 


i changed before ["sam.c" 


:41] : 






old value = 


19; 








new value - 


1; 






[25] 


i changed before ["sam.c" 


:41] : 






old value = 


1; 








new value - 


14; 






[Printline :58,Qx2f 8] : i=14 






[23] 


[Printline: 58, 0x2f 8] 


pline->st 


ring) ; 


1. 


( 14) struct line { 








[25] 


i changed before ["sam.c" 


:41] : 






old value = 


14; 








new value = 


22; 






More 


(n if no)n 








Escape from listing 








(dbx) 











( 



Writing Conditional Code in DBX (when) 



The when command is for use with conditional debugger code. It lets you 
specify a condition (for example, a line number, an expression, or a procedure 
name). When DBX encounters that condition, it executes the commands that 
you specified. 



( 
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Syntax: 



Command 


Select this command to... 


when VAR [if EXP] {COMMANDJJIST} 


Execute the command list when 
VAR changes. 


when [VAR] at LINE [if EXP] 
{COMMAJSTD_LIST} 


Execute the command list when 
VAR changes and the debugger 
encounters line. 


when in PROCEPURE {COMMAND_LIST} 


Execute the command list upon 
entering PROCEDURE. 


when [VAR] in PROCEDURE [if EXP] 
{COMMAND_LIST} 


Execute the specified commands 
on each line of PROCEDURE 
when EXP is true and VAR 
changes. 



NOTE: EXP is checked before VAR. 
Example: 



(dbx) when in Printline {print i} 
[14] print i in Printline 
(dbx) rerun 

[14] stopped at [printline: 58, 0x2f 8] 
(dbx) cont 

0, (19) #include <stdio.h> 
1 4 t0i 


pline->string) ; 


[14] stopped at [printline: 58, 0x2f 8] 
(dbx) cont 

1. (14) struct line { 
99 ^€ 


pline->strmg) ; 
valnpofi 


[14] stopped at [printline: 58, 0x2f 8] 

(dbx) when in printline {stop} 

[15] stop in printline 

(dbx) reurn 

[15] stopped at [printline: 58, 0x2f8 

(dbx) i 

DBX stops in the 
procedure printline 


pline->string) ; 
I pline->string) ; 



Stopping at Signals (catch and ignore) 



The catch command lists the signals that DBX catches or specifies a signal for 
DBX to catch. If a child in the program encounters a specified signal, DBX 
stops the process and gives you control. 
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Syntax: 



c 



Command 


Select this command to... 


catch 

catch SIGNAL 
ignore 

ignore SIGNAL 


Print a list of all signals that DBX 
will catch. 

Add a signal to the catch list. 

Print a list of all signals that DBX 
will not catch. 

Remove a signal from the catch list 
and add it to the ignore list. 



Example: 



(dbx) catch 

INT QUIT ILL TRAP IOT EMT FPE BUS SEGV SYS PIPE TERM STOP TTIN 
TTOU TINT SCPU XFSZ 
(dbx) ignore 

HUP KILL ALRM TSTP CONT CHLD 
(dbx) catch kill 
(dbx) catch 

INT QUIT ILL TRAP IOT EMT FPE KILL BUS SEGV SYS PIPE TERM STOP 
TTIN TTOU TINT XCPU XFSZ 
(dbx) ignore 
HUP ALRM TSTP CONT CHLD 

(dbx) A adds KILL 

J to the catch 

removes KILL list 

from the ignore 
list 



t 



c 



Examining Program State 

This part of Chapter 5 shows you how to do these things: 

• print stack traces 

• move up and down the activation levels of the stack 

• print variable values 

• print register values 

• print information about the activation levels in the stack trace 
Doing Stack Traces (where) 

The where command does stack traces. Stack traces show the current activation 
levels (procedures) of a program. This command doesn't trace variables. 



c 
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Syntax: 



Command 


Select this command to... 


where 


Do a stack trace. 



Example: 

If a breakpoint is set in printline in the sample program sam.c, (see Sample 
Program at the end of this chapter), the program runs and stops in the proce- 
dure main. Then, by typing cont followed by where, a stack trace executes, 
providing the information shown below. 



(dbx) stop in printline 
[1] stop in printline 

(dbx) where 

>0 printline (pline = 0x7f f f 5b80) [*sam.c" :58, 0x2f 7] 
$blodkiPsam.c":47A0x2bb] A A A 

fpirgc - 2, argT =* 0x7f ffebad? PsaFa ^ m 

the current 
value of 
the argument 
pline 



2 main' 
dbx) 



the procedure 
name 



the activation 
level number — 
the > shows 
that the user is 
examining this 
activation level 



:47, 0x2bb] 

the program 
I — counter 



the line 
number 



the source 
file name 



NOTE: In the example, $blockl has the same program counter as main. This 
indicates that main has a block with locally scoped variables in it, which doesn't 
appear to all of main. 



Moving Up and Down the Stack (up, down) 



The up and down commands move up and down the activation levels in the 
stack. These commands are useful when examining a call from one level to an- 
other. You can also move up and down the activation stack with the func com- 
mand. For a definition of activation levels, see What Are Activation Levels? 
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Syntax: 



Command 


Select this command to... 


up [EXP] 
down [EXP] 


Move up the specified number of 
activation levels in the stack, The 
default is one level. 

Move down the specified number of 
activation levels in the stack, The 
default is one level 



Example: 



c 



moves 

down one level 



(dbx) where 

>0 Printline (pline ** 0x7f £ f 5b80) ["sam.c" :58 r 0x2 f 7] 

1 $blockirsam.c":47, 0x2bb] 

2 main(argc « 2, argv = 0x7fffeba0) [^sam.c" : 47, 0x2bb] 
(dbx) down 

$blockl Psam,c":47,0x2bb] 
(dbx) where 

printline (pline = 0x7f f £ 5b80) (^sam.c" : 58, 0x2f 7 1 
>1 $blockir3am.c'':47, 0x2bb] «* ~ — ' ■ " ^ 

2 main(argc = 2 r argv * Ox7fffebaO) [^sam.c" : 47, 0x2bb] 

(dbx) up moves up 

Printline (pline <* 0x7f f f 5b80) ["sam.c"' :58, 0x2f 7] f f 

(dbx) where one level 

>0 Printline (pline * 0x7f f f 5b80) Psam.c" : 58, 0x2f 7' 

1 $blockiPsam.c'':47,0x2bb] 

2 main(argc ~ 2, argv - Qx7£ffeba0) Psam. : 47, 0x2bb] 
(dbx) 



( 



Printing (print and print!) 



The print commands lists the value of one or more expressions. You can also 
use print to display the program counter and the current value of registers; see 
the next section, Printing Register Variables, for details. 

The printf command lists information in a format you specify and supports all 
formats of the PRINTF command except %$, For a full list of formats, see the 
PRINTF(3S) manual page in the UNIX Programmer' s Manual. You might use 
printf when you want to see a variable's value in a different number base. The 
command alias list has some useful aliases for printing the value of variables in 
different bases— octal (po), decimal (pd), and hexadecimal (px). The default 
number base is decimal. See Creating Command Aliases* 



5-48 



Languages Programmer's Guide 



Debugging Your Code 



Syntax: 



Command 


Select this command to,.. 


print EXP1, . , . ,EXPN 

printf "STRING", EXP1, . . . , EXPM 


Print the value of the 
specified expressions. 

Print the value of the 
specified expressions 
in the format as specified 
by the string. 



Note: If the expression has the same name as a dbx keyword, it must be en- 
closed within parentheses, For example, in order to print output, a keyword in 
the playback and record commands, you must specify: 

print (output) 
Example: 



(dbx) 
14 ***"" 



print i 



(dbx) pd i 

14 ^ — ' 

(dbx) po i 

Olff* 

(dbx) px i 

Oxe<— 

(dbx) 



decimal 



decimal 



octal 



hexadecimal 



Printing Register Values (printregs) 



The printregs command prints register values, both the real machine register 
names and the software (from the include file regdefs.fi) names. A prefix before 
the register number specifies the type of register; the prefixes used and their 
meanings are shown in the table below: 



Prefix 



$r 
$f 
$d 
$pc 



Register Type 



Machine register. 

Floating point. 

Double precision floating point. 

Program counter value,. 



You can also specify prefixed registers in the print command to display a regis- 
ter value or the program counter. For example, 

print $r3 
print $pc 

print the values of machine register 3 and the program counter respectively. 
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You set the DBX variables $hexints and $hexouts to specify that the listing use 
hexadecimal, 

Syntax: 



c 



Command 


Select this command to.,. 


psintregs 


Print the current values of all 
registers. 



Example: 



(dbx) printregs 








rO/zero-O 


rl/at=l 


r2/v0-19 


r3/vl-0 


r4/a0-2147441472 


r5/al=34838 


£6/a2-4096 


r7/a3-80 


r8/t0=19 


r9/tl=34816 


rl0/t2-19 


rll/t3-0 


rl2/t4=l 


rl3/t5=34820 


i:14/t6-Q 


rl5/t7-l 


rl6/s0-2147441472 


rl7/sl=0 


rl8/s2-Q 


rl9/s3-0 


r2Q/s4=0 


r21/s5=0 


r22/s6=0 


r23/s7-0 


r24/t8=4086 


r25/t9=255 


r2 6/k0-0 


r27/kl-0 


r28/gp=50529 r29/$0=2147441400 


r30/fp-2147442536 


r31/ra-700 


$f0= 0.0 


$fl = 0.0 


$f2= 0.0 


$f3- 0.0 


$£4= 0.0 


$f5= 0.0 


$f6= 0.0 


$£7- 0.0 


$f8- 0.0 


$f9= 0.0 


$£10=0,0 


$£11-0.0- 


$f 12-0.0 


$f 13-0,0 


$f 14*0.0 


$f 15-0,0 


$£16=0.0 


$f 17=0.0 


$f 18=0.0 


$fl9-Q.Q 


$f 20-0.0 


$f 21-0.0 


$f 22-0.0 


$f 23=0.0 


$f24=0.0 


$£25=0.0 


$f 2 6-0.0 


$f 27-0.0 


$f28=0.0 


$£2 9=0.0 


$f 30-0.0 


$£ 31-0.0 


$dQ- 0.0 


$d2= 0.0 


$d4= 0.0 


$d6- 0.0 


$d8- 0.0 


$dl 0=0.0 


$d!2-0.0 


$dl4-0.0 


$dl 6-0.0 


$dlS=0.0 


$d20=*0.0 


$d22-0.0 


$d24-0.Q 


$d2 6=0.0 


$d28=0.0 


$d30-0.0 


$pc- 760 








(dbx) 









Printing Information about Activation Levels (dump) 



The dump command prints information about activation levels. For example, 
this command prints values for all variables local to a specified activation level, 
To see what activation levels you have in your program, use the where com- 
mand to do a stack trace. 



( 



( 
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Syntax: 



Command 


Select this command to... 


dump 
dump . 

dump PROCEDURE 


Print information about the current 
activation level. 

Print information about all activation 
levels in your program. 

Print information about the specified 
procedure (activation level). 



Example: 



(dbx) where 

>0 Printline (pline=0x7f f f 5b80) [ xx sam.c" :58, 0x2f7] 
1 $blockl rsam,c":47,0x2bb] 
(dbx) dump 

Printline (pline«0x7f ff 5b80) Psam.c" :58, 0x2f 7] 
(dbx) dump . 
> Printline (pline~Qx7f ff5b80) Psam.c" :58, 0x2£7] 

1 $blockl psam.c": 47, 0x2bb] 
curlinenumber = 1 

i=19 

2 main (argc=2, argv=0x7f f febaO) Psam.c" : 47 f 0x2bb] 
fd = 0x4270 

linel-struct { 
string= >> #include<stdio.h> 

linenumber=0 

} 

in ""; 

(dbx) dump main 

main (argq=2, argv»0x7f ffebaO) Psaam.c" : 47, 0x2bb] 
fd=0x4270 
linel=struct { 
string="struct line { 
length =14 
linenumber = 1 
} 
(dbx) 



Debugging at the Machine Level 



DBX provides some commands specifically for people who need to debug as- 
sembly code. The commands described in this section let you do the following; 

• set breakpoints 

• execute single lines of code 

• trace variables 

• print the contents of memory addresses 

• disassemble instructions 
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Setting Breakpoints in Machine Code (stopi) 



The stopi commands set breakpoints in machine code, These commands work 
in the same way as the stop at, stop in, and stop if commands as described in 
the section Setting Breakpoints, except for the stop at command, where an 
address instead of a line number is specified. 



Command 


Select this command to... 


stopi [VAR] at 
stopi [VAR] at LINE 

stopi [VAR] at LINE 
if EXP 

stopi if EXP 

stopi VAR if EXP 

stopi in PROCEDURE 

stopi VAR in PROCEDURE 

stopi in PROCEDURE if EXP * 

stopi VAR in PROCEDURE 
if EXP* 


Stop at the current line. 
Stop at a specified address. 

Stop at a specified address only 
ifEXPistrue. 

Stop if EXP is true. 

Stop if VAR changes and EXP is true. 

Stop at the beginning of the procedure. 

Stop in the specified procedure when 
VAR changes. 

Stop in the specified procedure if EXP 
is true. 

Stop in the specified procedure when 
VAR changes and EXP is true. 


* 
EXPxs cheqked before VAR. 





( 



( 



Example: 



(6hx) stopi at Qx2f8 

[2] stopi at ^sam.c";760 

(dbss) rerun 

[2] stopped at [Printline; 58, 0x2f 8] pline~> string); 
(dbx) 



( 
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Continuing after Breakpoints in Machine Code (conti) 

The conti commands continue executing assembly code after a breakpoint. 
Syntax: 



Command 


Select this command to.,. 


conti SIGNAL 


Send the specified signal and 
continue. 


conti to ADDRESS 


Continue until reaching the 
specified address. 


conti in PROCEDURE 


Continue until the beginning of 
the specified procedure. 


conti SIGNAL to ADDRESS 


Continue until reaching the 
specified address, then send 
the signal. 


conti SIGNAL in PROCEDURE 


Continue until reaching the 
beginning of the specified 
procedure, then send the 
signal. 



Example: 



(dbx) conti 
















(19)#inolude 


<stdio 


.h> 












[2] stopped at 
lw r2, 32 (sp) 
(dbx) 


[Printline: 


58, 


0x2f8] 


pline- 


->st 


ringO; 



Executing Single Lines of Machine Code (stepi and nexti) 

The stepi and nexti commands execute a fixed number of machine instructions 
as specified by EXP. If you don't specify EXP for stepi and nexti, DBX exe- 
cutes one machine instruction. If you specify EXP, DBX executes the machine 
instructions as follows; 

• For stepi and nexti, DBX does not take comment lines into 
consideration in interpreting EXP. The program executes EXP 
machine instructions, regardless of the number of comment 
lines interspersed among them. 

• For stepi, DBX considers EXP to apply to both the current pro- 
cedure and to procedure calls Q&l and jalr). The program stops 
after executing EXP instructions in the current procedure and 
any called procedures, 
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• For nexti, DBX considers EXP to apply to only the current pro- 
cedure. The program stops after executing EXP instructions in 
the current procedure, regardless of the number of instructions 
executed in any procedure calls, 

Use stepi and nexti to execute source lines after a breakpoint. 
Syntax: 



c 



Command 


Select this command to,.. 


stepi [EXP]* 
nexti [EXP] * 


Execute the specified number of lines of source 
code, EXP refers to the number of lines to 
be executed in both the current procedure and 
any procedure calls. 

Execute the specified number of lines of source 
code, EXP refers to the number of lines to 
be executed in only the current procedure, 
regardless of any procedure calls. 


*Defaultis 1, 



Example: 



(dbx) rerun 

[2] stopped at [printline:58, 0x2f 8] pline~>string) ; 

(dbx) stepi 

[Printline ; 58+0x4, Qx2f c] pline->string) ; 

lui rl f 0x0 

(dbx) 



( 



Tracing Variables in Machine Code (trace!) 



The tracei commands track, one instruction at a time, changes to variables. The 
tracei commands work for machine instruction as the trace commands do for 
lines of source code. 



( 
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Syntax: 



Command 


Select this commattd to... 


tracei VAR 




Print the value of the 
variable as it changes 
instruction by instruction. 


tracei VAR at 


ADDRESS 


Print the value of the variable 
when it changes instruction by 
instruction. 


tracei VAR in 


PROCEDURE 


Print the value of the variable 
when it changes in the specified 
procedure. 


tracei VAR at 


ADDRESS if EXP 


Print the value of the variable 
at the specified address when 
the expression is true, 


tracei VAR in 


PROCEDURE if EX P Print the value of the variable 

in the specified procedure 
when it traces instruction by 
instruction. 



Printing the Contents of Memory 



Entering values in the syntax shown below prints the contents of memory ac- 
cording to your specifications. 

Syntax: 



Command 


Select this command to... 


ADDRESS /<COUNT><MODE> 


Print the contents of the 
specified address for the 
specified count. 



The parameter address is the address of the first item to be listed, count is the 
number of items to be listed, and mode is one of the characters shown in the 
table below specifying the item. 
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Mode 


Select this mode to... 


d 


Print a short word in decimal/ 


D 


Print a long word in decimal, 


o 


Print a short word in octal. 





Print a long word in octal. 


x 


Print a short word in hexadecimal. 


X 


Print a long word in hexadecimal. 


b 


Print a byte in octal. 


c 
s 


Print a byte as a character. 

Print a string of characters that ends in a null 

byte. 


f 
g 


Print a single precision real number, 
Print a double precision real number. 


i 


Print machine instructions. 



c 



Example: 

When you look at memory, you will see something like this; 



(dbx) 0x2f8/10i 






[Printline : 58 , 0x2f 8 ] 


lw 


r2 f 32(sp) 


[Printline :58, 0x2fc] 


lui 


rl,0x0 


[Printline : 58 , 0x30 ] 


addiu 


r4,rl, 16860 


[Printline: 58, 0x304] 


lui 


rl,0xQ 


[Printline : 58 , 0x30 8 ] 


addiu 


r5,rl, 16780 


[Printline :58 f 0x30c] 


lw 


r6,260(r2.) 


[Printline: 58, 0x310] 


lw 


r7,256(r2) 


[Printline: 58, 0x314] 


jal 


fprintf ! ! 


[Printline: 58, 0x318] 


sw 


r2,16(sp) 


[Printline : 59, 0x31c] 


lui 


rl,0x0 


[Printline: 59, 0x320] 


jal 


fflush<! 


[Printline: 59, 0x324] 


addiu 


r4,rl, 16960 


(dbx) 0x2f8/10d 






000002f8: 32 3677 


15361 1690 9252 15361 


00000308: 16780 9253 




(dbx) 







( 



( 
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When you disassemble instructions, you will see something like this: 



(dbx) &printline/10i 
* [Printline : 58, 0x2ec] 
[Printline : 58 , Qx2f0] 
[Printline ?58,0x2f 4] 
[Printline: 58, 0x2f8] 
[Printline :58, 0x2fc] 
[Printline; 58, 0x300] 
[Printline: 58, 0x304] 
[Printline :58 f 0x308] 
[Printline : 58 f 0x30c] 
[Printline : 58 , 0x310] 
(dbx) &printline/10d 
000002eo: 65504 1017 
4496428 44 
000002fc:0 
(dbK) 



addiii 


sp,sp,-32 


$W 


f4,32(sp) 


sw 


r31 f 28(sp) 


lw 


r2,32(sp) 


lui 


r 1,0x0 


addiu 


r4,rl, 16960 


lui 


rl,0x0 


addiu 


r5,rl, 16780 


lw 


r6,26Q(r2) 


lw 


r7,25GU2) 


3 32 44963 23 15361 


991 32 


36770 



Debugger Command Summary 



Table 5.3 lists all commands (except for command line editing commands) and 
gives each commands syntax. For a full description of each command, refer to 
the command's long description. 
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DBX Command Summary 


Command 


Alias 


Select this command to.,. 


Syntax 


/ 




Search ahead in 
the code for the 
specified string. 


/REGEX 


? 




Search back in 
the code for the 
specified string. 


?REGEX 


t 




Specify a command 
from your history 
list. 


ISTRING 

!INT 

!-INT 


alias 




List all existing 
aliases, or, if you 
specify an argument, to 
define a new alias. 


alia 5 [NAME (ARG1 , . . . 
ARGN) "STRING"] 


assign 


a 


Assign the specified 
expression to a 
specified program 
variable. 


assign EXP1 - EXP2 


catch 




List all signals that 
DBX catches, or, 
if you specify an 
argument, to add a 
new signal to the 
catch list. 


catch [signal] 


cont 


c 


Continue executing 
a program after a 
breakpoint. 


cont 

cont in PROCEDURE 
cont to LINE 
cont SIGNAL to LINE 
cont SIGNAL in PROCE- 
DURE 



c 



( 



Table 53 (J of 7). Command Summary, 
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DBX Command Summary 


Command 


Alias 


Select this command to... 


Syntax 


conti 




Continue executing 
assembly code after 
a breakpoint. 


conti SIGNAL 
conti to ADDRESS 
conti in PROCEDURE 
conti SIGNAL to ADDRESS 
conti SIGNAL in PROCEDURE 


delete 


d 


Delete the specified 
item from the status 
list. 


delete EXP1, .. .EXPN 
delete ALL 


down 




Move down the 
specified number of 
activation levels in 
the stack. The de- 
fault is one level. 


down [EXP] 


dump 




Print variable infor- 
mation about the 
procedure. If you 
specify a dot (.), 
this command prints 
global variable informa- 
tion for all procedures. 


dump PROCEDURE 
dump , 


edit 




Call an editor 
from DBX. 


edit [FILE] 


file 


e 


Print the name of 
the current file, or, 
if you specify a 
filename, this 
command changes 
the current file 
to the specified 
file. 


file [FILE] 


func 


f 


Move to the 
specified procedure 
(activation level) 
or print the current 
activation level. 


funp 

func EXP 

func PROCEDURE 


goto 


g 


Go to the specified 
line. 


go1;o LINE 



Table 5.3 (2 of 7). Command Summary , 
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DBX Command Summary 


Command 


Alias 


Select this command to..* 


Syntax 


help 


? 


Print a list of DBX 
commands. Uses 
UNIX system more. 


help 




history 


h 


Print a list of the 
previous commands 
that you've issued- The 
default is 20. 


history 




ignore 




List all signals that 
DBX does not catch, 
or, if you specify an 
argument, add the 
specified signal to 
the ignore list. 


ignore [SIGNAL] 




list 


1 


List the specified 
lines. The default 
is 10 lines, 


list 

list [EXP: INT] 

list [EXP] 




next 


n 


Step over the 
specified number of 
lines. The default 
is one. This com- 
mand does not step 
into procedures. 


next [INT] 




nexti 


ni 


Step over the 
specified number of 
machine instructions. 
The default 
is one. This com- 
mand does not step 
into procedures. 


nexti [INT] 




playback 
input 


Pi 


Replay commands 
that you saved with 
the record input 
command in a text 
file. 


playback input 


[FILE] 



( 



( 



Table 5 J (3 of 7). Command Summary. 
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DBX Command Summary 


Command 


Alias 


Select command to... 


Syntax 


playback 
output 


po 


Replay debugger 
output that you 
saved with the 
record output 
command. 


playback output [FILE] 


print 


P 


Print the value 
of the specified 
expression. 


print EXP1, . . . ,EXPN 


printf 


pd 


Print the value 
of the specified 
expression, using 
C string formatting. 


printf * STRING", 
EXP1,.,.EXPN 


printregs 


pr 


Print all register 
values. 


printregs 


quit 


q 


Exit DBX 


quit 


record 
input 


ri 


Record all commands 
you type to DBX. 


record input [FILE] 


record 
output 


ro 


Record all DBX 
output. 


record output [FILE] 


return 




Continue executing 
until the procedure 
returns. If you 
don't specify a 
procedure, DBX 
assumes the next 
procedure. 


return [PROCEDURE] 


run 




Run your program. 


run [ARG1 . . . ARGN] 
[<FILE1] [>FILE2] 


rerun 


r 


Run your program 
again, using the same 
arguments you 
specified to the 
run command. 


rerun [ARG1 . . . ARGN] 
[<FILEJ1] [>FILE2] 



Table 53 (4 of 7). Command Summary. 
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DBX Command Summary 



Command 



set 



sh 



source 



status 



Alias 



step 



stepi 



stop 



si 



b 
bp 



Select command to,, 



See the list of existing 
debugger variables and 
their values, assign a 
value to a variable, or 
define a new variable 
and assign a value to 
it. 

Call a shell from 
DBX, or, execute 
a shell command. 

Execute DBX 
commands from the 
specified file. If 
you don't specify 
a file name, DBX 
assumes that you 
want the file you 
created with the 
record inputom- 
mand. 

Print a list of 
currently set break- 
points, record 
commands, and 
traces. 

Step the specified 

number of lines. 

Tbis command steps into 

procedures. The default 

is one line. 

Step the specified num- 
of machine instructions. 
This command steps 
into procedures. The 
iefault is one instruction. 

Set a breakpoint 
at the specified 
point. 



Syntax 



set 

set VAR *> EXP 



sh [SHELL COMMAND] 



source [FILE] 



status 



step [INT] 



( 



( 



stepi [INT] 



stop [VAR] at 

stop [VAR] at LINE 

stop [VAR] in PROCEDURE 

stop [VAR] if EXP 

stop [VAR] at LINE if EXE 

stop [VAR] in PROCEDURE 
if EXP 



Table 5 J (5 of 7). Command Summary. 
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Command 



Alias 



Select command to., 



Syntax 



stopi 



trace 



tr 



tracei 



unalias 



unset 



up 



use 



Set a breakpoint 
in machine code 
at the specified 
point. 



Trace the specified 
variable. 



Trace the specified 
variable in the 
machine instruction. 



Remove specified alias. 



Unset a debugger 
variable. 



Move the specified 
number of activation 
levels up the stack. 
The default is one. 

Print a list of the 
source directories, 
or, if you specify 
a directory name, 
this command substitute 
the new directories for 
the previous list. 



stopi [VAR] 
stopi [VAR] 
stopi [VAR] 
stopi [VAR] 

EXP 
stopi [VAR] 

if EXP 



at ADDRESS 
in PROCEDURE 
if EXP 
at ADDRESS if 

in PROCEDURE 



trace VAR 
trace VAR at LINE 
trace VAR in PROCEDURE 
trace VAR at LINE if 

EXP 
trace VAR in PROCEDURE 

if EXP 

tracei VAR 

tracei VAR at ADDRESS 
tracei VAR in PROCEDURE 
tracei VAR at ADDRESS 

if EXP 
tracei VAR IN 

PROCEDURE if EXP 



unalias ALIAS NAME 



unset VAR 



up [EXP] 



use [DIR1 DIR2. , .DIRN] 



Table 5,3 (6 of 7), Command Summary. 
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DBX Command Summary 


Command 


Alias 


Select command to,.. 


Syntax 


whatis 




Print the type 
declaration for the 
specified name. 


whatis VAR 


when 




Execute the 
specified DBX com- 
mands during 
execution. 


when [VAR] [if EXP] 

{COMMAND LIST} 
when [VAR] at LINE 

[if EXP] {COMMAND 

LIST} 
when [VAR] in PROCEDURE 

[if EXP] {COMMAND 

LIST} 


where 


t 


Do a stack trace, 
which shows the 
current activation 
levels. 


where 


whereis 




Print all qualifications 
of the specified 
variable name. 


whereis VAR 


which 




Print the qualification 
of the variable name 
currently in use. 


which VAR 


examine 
address 




Print the contents of 
the specified address 
or disassemble the 
code for the instruction 
at the specified address. 


ADDRESS/<COUNT><MODE> 



c 



Table 5.3 (7 of 7), Command Summary. 



Sample Program 



In this chapter, we use a sample program to illustrate debugger commands. The 
program sam.c counts non-blank lines in a program. 

The sample C program, sam.c, consists of the code shown on the next page. 



c 
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#include <Stdio , h> 

struct line { 
char string [256] ; 

int length; 

int linenumber; 

}; 

typedef struct line LINETYPE; 
void Printline () ; 
main (argc, argv) 
int argc; 

char **argv; 

{ 
LINETYPE linel; 

FILE *fd; 

extern FILE *f open ( ) ; 
extern char *fgets ; 
if (argc <2) { . 
fprintf (stderr, "Usage sam filename\n") ; 
exit (1) ; 
} /* if*/ 

fd=fopen (argv[l], "r") ; 
if (fd==NULL) { 
fprintf (stderr, "cannot open %s\n", argv[l]); 
exit (1) ; 
} /* if*/ 

/* loop through the lines in a file and call a routine to print 
those that are not blank along with their lengths and linenumber. 

*/ 

while ( f gets (linel. string, sizeof (linel. string) , fd) ! = NULL) { 
int i ; 

static curlinenumber = 0; 
i = strlen (linel . string) ; 
if (i ===== 1 && linel. st ring [0] « '\n'.) 

continue; /* don't count blank lines */ 

linel .length - i; 

linel . linenumber = curlin$number++; 
Printline (&linel) ; 
} /* while */ 
} /* main */ 

void printline (pline) 
LINETYPE *pline; 

{ fprintf (stdout, "%3d. (%3d) %s", 
pline->linenumber pline->length f 

pline->string) ; 
fflush (stdout) ; 
} /* printline */ 
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Appendix A 
C Implementation 



The C language supported by the compiler is an implementation of the language 
defined in The C Programming Language by Kernighan and Ritchie (Prentice 
Hall, 1978). This appendix covers the following topics: 

• Specifying vararg macros, a requirement for all functions that 
take a variable number of arguments. 

• Deviations and extensions to the C language, as defined in The 
C Programming Language by Kernighan and Ritchie (Prentice- 
Hall). 



Translation limits. 



Vararg. h Macros 



If a function takes a variable number of arguments (for example, the C library 
functions printf and scanf), you must use the macros (defined in the varargs.h 
header file) shown below. 



/* @ (#)varargs.h 1.2 


*/ 






typedef 


char *va list; 








#def ine 


va 


del int va alist; 






#def ine 


va 


start (list) list = (char *) 


&va 


alist 


#define 


va 


end(list) 








#def ine 


va 


arg(list f mode) 


( (mode *) (1: 


1st 


= \ 


(char 


*) 


(sizeof (mode) > 


4 ? (int) list + 


2*8 - 1 & -8 \ 


: (int)li 


st + 2*4 - 1 & - 


-4))) [-1] 






*/ 













The va_dcl macro declares the formal parameters va_alist, which is either the 
format descriptor for the remaining parameters or a parameter itself. 

The vajstart must be called within the body of the function whose argument 
list is to be traversed. The function can then transverse the list or pass its 
va_list pointer to other functions to transverse the list. The type of the vajstart 
argument is va_list; it is defined by the typedef statement in varargs.h. 

The va__arg macro accesses the value of an argument rather than obtaining its 
address. The macro handles those type names that can be transformed into the 
appropriate pointer type by appending an asterisk (*), which handles most sim- 
ple cases. The argument type in a variable argument list must never be an inte- 
ger type smaller than int, and must never be float. 

For more information on the varargs.h macros, see the varargs man page in the 
UNIX Programmer's Manual. Figure A.l shows an example of the use of 
varargs macros; the expected output from the example is as follows: 
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load i r 
load i 4 4 
add I 
store 10 4 



( 



#include stdio.h 



#include <vg.rargs.h> 

#include <stdio,h> 

enum operations {load, store, add f sub}; 

main () { 

void emit ( ) ; 
emit (load, 'I' , 0, 4) ; 
emit (load, ' l r , 4, 4) ; 
emit (add, ' •' I' ) ; 
emit (store, r I ' , 0, 4); 
} 

void 

emit ( op, va^alist ) 

/* emit takes a variable number of arguments and prints 
/* them according to the operation format */ 
enum operations op; 
va_dcl { 

va_list argjptr; 
register int length, offset; 
register char type; 
va_start (argjptr) ; 
switch (op) { 

case add: /* print operation and length*/ 
type = va_arg(arg_j3tr, int) ; 
printf("acfd %c n", type) ; 
break; 
case sub: /* print operation and length*/ 
type = va_arg(arg_j>tr, int) ; 
printfC'sub n", type); 
break; 
case load: /* print operation, offset and length */ 
type - va_arg(arg_ptr, int); 
offset = va_arg(arg_ptr, int); 
length - va_arg(arg_ptr, int); 



type, offset, length) ; 



printf ("load %c %d %d n" 
break; 
case store: 

type = va_arg(argjptr, int); 
offset = va_arg(arg_jptr, int); 
length - va_arg(arg_ptr, int); 
printf ("store %c %d %dn", type, offset, length); 



C 



A .1. Passing a Variable Number of Arguments to aC Function. 



Deviations 



C does not support the entry keyword, which has no defined use. Additionally, 
C does not support the asm keyword, as implemented by some C compilers to 
allow for the inclusion of assembly language instructions. 



c 
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Extensions 



Extensions to C include the following: 

• the enumeration type, a set of values represented by identifiers 
called enumeration constants; enumeration constants are speci- 
fied when the type is defined. For information on the align- 
ment, size, and value ranges of the enumeration type, see 
Chapter 2. 

• the void type, which allows you to specify that no value be re- 
turned from a function. 

• the volatile type modifier, which is used when programming 
I/O devices and the signed type. In addition, the const key- 
word has been reserved for future use. For more information 
on the volatile modifier, see Chapter 2. 



Translation Limits 



Table A.l shows the maximum limits imposed on certain items by the C com- 
piler. 



C Specification 


Maximum 


Nesting levels 

Compound statements 

Iterations 

Selections 

Conditional compilations 

Maximum number of type 
modifiers (arrays, pointers, 
function, volatile) 

Case labels 

Function call parameters, 

Significant characters 
External identifier 
Internal identifier 


<30 

9 

500 

150 

<32 



Table A.L C Compiler Limitations. 
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Pascal Implementation 



Names 



The Pascal language supported by the compiler is an implementation of ANSI 
Standard Pascal (ANSI/ IEEE770X3.97-1983). Pascal was originally designed 
as a language suitable for teaching programming concepts and one that would 
be efficient and reliable on available computers. 

Pascal extends the standard definition to provide features for application devel- 
opment and to meet the following objectives: 

• Provide extensions that make Pascal reasonable for a wide class 
of programs. 

• Anticipate the requirements of customers. 

• Be consistent with the direction of the emerging extended stan- 
dard. 

• Be consistent with the UNIX/C programming environment. 
The sections that follow describe the extensions in detail. 



Pascal provides several extensions that apply to identifiers, the names that a 
Pascal programmer uses. 



Use of Underscores 



Many users find it helpful to use the underscore character in identifiers. The 
underscore can be used to make names that are composed of several words. 
The underscore is also used in the C programming language; including the fea- 
ture in Pascal makes it possible to call to those C functions that require an un- 
derscore. 

The compiler treats the underscore as an alphabetic character; it can be placed 
in any position of the identifier including the first, as shown below. 

read__integer 
_bitsjper__word 

Lowercase in Public Names 

Pascal does not distinguish between uppercase and lowercase in respect to vari- 
able names. This causes a problem for those names meant to be linked with C 
functions, where case is significant. 

Pascal converts all names that are used to refer to external variables, procedures, 
or functions into lowercase. 
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Pascal permits alphabetic labels in addition to numeric labels as specified by the 
Pascal standard. 



Constants 

Non-Decimal Number Constants 



String Padding 



c 



( 
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It is often useful to write integer constants in a radix other than base 10. This 
occurs in programs that use data structures defined by the system. Other than 
base 10, base 2, 8, and 16 are the most frequently used bases. 

Pascal allows the use of any base from 2 through 36. You can specify a num- 
ber in those bases by using the form; 

baseftnumher 

The base is a decimal number in the range 2 to 36. The number after the base 
is a number in the specified radix using a..z (either case) to denote the values 10 
through 25. 

The number must specify a value in the range 0..maxint (2147483647). The 
following example shows the number 42 in several different bases. 

2#101010 

3#1120 

4#222 

8#52 

42 

10#42 

11#39 

16#2a 

If the radix is a power of two (2, 4, 8, 16, or 32), the number may be negative if 
it specifies a 32-bit value. For example, 16#8000000 is -2147483648, which is 
the smallest integer contained in a 32-bit number. 



Standard Pascal requires that a literal character string have the same length as 
the variable with which it is used. Manually adding extra blanks invites errors, 
and changing a Pascal type definition would require manually changing all lit- 
eral strings that are used with variables of that type. 

Pascal pads a string constant with blanks on the right according to its use. That 
is, assigning a 3-character literal to a 6-character variable causes the string lit- 
eral to be treated as being 6 characters long. Assigning a 6-character literal 
string to a variable containing 3 characters causes an error. 

A string of length 1 is regarded as a character rather than a string. As a result, a 

string padding is not applied to a string of length 1. Add a blank space to the ^ 

single character if you want padding to take place. I 
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Non-Graphic Characters 



Literal character strings can't contain ASCII characters that have no graphic 
representation. The most commonly used characters that have no graphic repre- 
sentation are control characters. 

Pascal has a special form of a character string, enclosed in double quotation 
marks, in which such characters may be included. A backslash escape character 
is used to signal the use of a special character. For example, the following line 
rings (beeps) the bell on an ASCII terminal. 

writeln (output/ "\a"); 

The following table lists the escape character sequence used to encode special 
characters. 



Character 


Result 


\a 


alert (16#07) 




\b 


backspace (16#08) 




\f 


form feed (16#0c) 




\n 


newline (16#0a) 




V 


carriage return (16#0d) 




\t 


horizontal tab (16#09) 




\v 


vertical feed (16#0b) 




\\ 


backslash (16#5c) 




\" 


quotation mark (16#22) 




V 


single quote (16#27) 




\nnn 


character with octal value of nnn. 




\xww 


character with hexadecimal value of 


nnn. 



Constant Expressions 



Using a constant expression in type definitions or constant definitions often 
makes programs easier to read and maintain. The following example shows the 
use of a constant expression — changing a single definition (array_size) changes 
both the size of the array and the definition of the index type used to access it. 



const 












array 


size = 


100; 








type 












array 


index 


= 0. . 


array_ 


size- 


-1; 


var 












v : array [ a 


rray_ 


_index 


] of 


integer; 
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Pascal permits a constant expression to be used where a single integer or scalar 
constant is ordinarily used, An expression can consist of any of the following 
operators and predefined functions: 



( 



Operator 


Function 


+ 


addition 


— 


subtraction and unary minus 


* 


multiplication 


div 


integer division 


mod 


modulo 


= 


equality relation 


<> 


inequality relation 


< 


less than 


<= 


less than or equal 


>= 


greater than or equal 


> 


greater than 





parenthesis 


bitand 


bit-wise and 


bitor 


bit-wise or 


bitxor 


bit-wise exclusive or 


lshift 


logical left shift 


rshift 


logical right shift 


Ibound 


low bound of an array 


hbound 


high bound of an array 


first 


lowest value of a scalar type 


last 


highest value of a scalar type 


sizeof 


the size (in bytes) of a data type 


abs 


absolute value 


chr 


inverse ordinal value for a character 


ord 


the ordinal value of a scalar value 


pred 


the predecessor to a scalar value 


succ 


the successor to a scalar value 


type- 


converts from one type to another 


functions 





( 



Pascal does not permit the use of a leading left parenthesis in constant expres- 
sions for the lower value of subrange types. That is, 

subrange = (11+12) *13 .. 14+15; 
mistakenly assumes the type is an enumeration instead of a subrange. 
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Statement Extensions 



Ranges in Case Statement Constants 

Pascal permits the specifications of value ranges in a case statement. The selec- 
tors in a case statement may be specified using the Pascal range notation to 
mean all values inclusive, as shown in the following example. 



II 1900. . 1999 | 

!§ 1800..1999f 

II 1700..1799f 

II 1600. .16991 



mini i iiiiiiinii iiiiiiiii i n 

"writ0ln< # «ifirbt^^»tbL century'); j 




Otherwise Clause in Case Statement 



Pascal extends the case statement to allow an otherwise clause, which is the 
default statement when no case clause equal to the case value exists. Any num- 
ber of statements can be included between otherwise and end, as shown in the 
preceding example. 

If no otherwise is specified, and no case clause satisfies the case selector values 
during execution, a case error warning message is printed. 



Return Statement 



Pascal provides a return statement that permits a procedure or function to re- 
turn to the caller without branching to the end of the procedure or function. If 
used within a function, return may be coded with an optional expression. The 
last value assigned to the function name is returned unless this expression is 
specified. Using the return statement is equivalent to assigning the value in 
the expression to the function name and executing a goto to the end of the rou- 
tine. 



lliiililli 


factorial in * iatager) 


s integer? 


if n 


= 1 then 


return (1) 




iiliiiiiii 


|ll|i;i|:||| 


||I|ii|||||lP 


WKmmB^^^^^^^^m 
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Continue Statement 



The continue statement causes the flow of control to continue at the next itera- 
tion of the nearest enclosing loop statement (for, while, or repeat). If the state- 
ment is a for statement, the control variable is incremented and the termination 
test is performed. 



c 



for J :- 1 to i do begin ^ 

if Line [J] = ' r then coatinuer 

write (output, Line:J); 
end {for}; 



Break Statement 



The break statement causes the flow of control to exit the nearest enclosing 
loop statement (for, while, or repeat). This feature permits you to end a loop 
without using the test specified on the loop statement, 



while p <> nil do begin 




p := p",next 
end; ^ 




a :- i; '* " ' ' ' 





( 



Declaration Extensions 
Separate Compilation 



Pascal permits breaking a program into several compilation units, one that con- 
tains the main program, and the others containing procedures and functions 
called by the main program; the procedures and functions it calls need not be 
written in Pascal. Pascal also permits separately compiled compilation units to 
share data. 



The compilation unit that contains the main program (the program compilation 
unit) follows standard Pascal syntax for a program. A compilation unit that 
contains separately compiled procedures and functions is called a separate com- 
pilation unit. Only one program compilation unit is permitted. 

In a separate compilation unit, procedures, functions, and variables are placed 
sequentially without any program header or main program block. 

Pascal allows Pascal declarations to be placed before the program header, 
whereas standard Pascal does not. All procedures, functions, and variables pre- 
ceding the program header are given an external scope. This means that they 



( 
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may be called (procedures and functions) or used (variables) by separate compi- 
lation units. The following example illustrates a program compilation unit: 



Header file extems.h 




const 

vector__size = 100; 
type 

vector_index =* . . vector_size-l; 

vector = array [vector__index] of integer; 
var 

v : vector; 
procedure initialize; 

external; 
function sum (var vect : vector) : integer; 

external; 



♦include "externa ,h A 



program main (output) ; 
begin 

initialize; 

writeln (sum(v) ) ; 
end. 



Figure B.L External Declarations in a Program Compilation Unit. 

In Figure B.l, external directives and other statements in the header file ex- 
terns.h specify that initialize and sum (used by the main program) and their pa- 
rameters are defined in a separate compilation unit. The external directive can 
be used to qualify only unnested routine names. 

Initialize and sum must be defined when the main program is link edited. Con- 
sider the following example, where mainone.p contains the Pascal source code 
for the main program and bodies.o contain a previously compiled object module 
of initialize and sum: 



pc -c mainone.p Compiles main program. 

pc -o exec mainone.o bodies.o Link edits the main program 

with sum and initialize. 



The external directive is similar to the Pascal forward directive, because it de- 
clares a routine name and its parameters without defining the body of the rou- 
tine. The external directive can be used only to qualify unnested routine names. 

All procedures, functions, and variables at the outermost level are given an ex- 
ternal scope. Figure B.2 below shows the separate compilation unit that defines 
the routines shown in Figure B.l. 
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Header file externs.h 




const 

vector_size = 100; 
type 

vector_index = . .vector__size-l; 

vector = array [vector^index] of integer; 
var 

v : vector; 
procedure initialize; 

external; 
function sum (var vect : vector) : integer; 

external; 



#include "externs . h'* 



1; 



procedure initialize; 
var 

i : vector^index; 

begin 

for i := lbound (vector) to hbound (vector) do v[i] 
end {procedure initialize}; 
function aum; 
var 

i : vector__index; 
j ; integers- 
begin 
j := 0; 

for i :- lbound (vector) to hbound (vector) do j := j+vect [i] ; 
return ( j ) ; 
end {function sum}; 



C 



C 



Figure B.2. External Declarations in a Separate Compilation Unit. 

In Figure B.2, initialize and sum are defined with the external directive. 

Note that, in this example, the external declarations were placed in the include 
file externs X This reduces the chance of errors due to inconsistent declara- 
tions; such includes are recommended for statements shared by multiple compi- 
lation units. 



Shared Variables 



All variables that are declared at the outermost nesting of a compilation unit 
have an external scope and can be used in different compilation units. The vari- 
able can have only one initializing clause and can be placed in one compilation 
unit The previous example illustrates a variable, named v, that is accessed from 
both compilation units. 



( 
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Initialization Clauses 



Pascal permits an external variable to have a clause that initializes either a sca- 
lar, a set, an array, or a pointer. The BNF syntax of a variable declaration is 
extended to: 

var-decl : := identifier-list ":" type-denoter [ " :=" in- 
itial-clause ] 

initial-clause : := constant-expr | 

" [" initial-value-list "] " 

initial-value : := constant-expr [ ". . " constant-expr ] | 
constant-expr " : " constant-expr | 
"otherwise" ":" constant-expr | 
" [" initial-value-list "] " 

initial-value-list ::= initial-value I 

initial-value-list ", " initial-value 

For scalar types, this initialization is very simple: 

var 

a: integer := 5; 
letter: char :='x'; 
xl : real := 6.5; 

An initial value may also be given to a structured type (array or set); every ele- 
ment of an array must be initialized or given a specified default value. 



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^K^ 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 




'.,-^or - &££&ytl> .1(5(5 } o£ -.jr.fccrc: 


•• •"' •: • W. 


orange : hue := [red, yellow]; 






black : hue := 

[first (color) . .last (color) ] ; 






name : packed array [1.. 32] of char := 
'MIPS Computer Systems' ; 






vect : vector := 

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 
30 : 0, 1, 2, 3, 4, 5, 6, 7, 8, $ 
otherwise : 99] ; 


|||||||||||||||||| 




pointers : array [0 .. 127] of ^vector := 
[otherwise: nil]; 







The above clauses initialize two sets, a string and two arrays. All elements of 
the array vect, except the first ten elements and the ten elements starting at in- 
dex 30, are initialized to 99. The array pointers is initialized entirely to the 
value nil. 
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Relax Declaration Ordering 



The declaration clauses can be written in any order and may be repeated. The 
Pascal requirement that a declaration must precede any use must still be ob- 
served. 



Predefined Procedures 



c 



Assert 



Argv 



Date 



Time 



assert (boolean-expr [ f string] ) 

The assert procedure evaluates a boolean expression and signals an execution 
time error (similar to a checking error) if the value is not true. If you specify 
the optional string, the string is written to standard error, otherwise the message 

assertion error in Pascal program 

is generated along with the line number and file name of the assert statement 
that causes the error. 



argv (integer-expr, string-var) 

The argv procedure returns the Mh program argument, placing the result in a 
string. The string can be blank, padded, or truncated, as required. The value of 
the first parameter must be in the range Q..argc-L Argument is the name of 
the program. 



date (string-var) 

The date procedure returns the current date. The resulting string has the form 
yy/mm/dd, where yy is the last two digits of the year, mm is the number of the 
month (01 is January), and dd is the day of the month (01 is the first day). If 
the string is less than 8 characters long, data is truncated on the right; if the 
string is longer than 8 characters, the string is padded with blanks on the right. 



time (string-var) 

The time procedure returns the current time. The resulting string has the form 
hh:mm:s$, where hh is the hour (24-hour clock), mm is the minutes (00 means 
on the hour), and ss is the seconds (00 means on the minute). If the string is less 
than 8 characters long, data is truncated on the right; if the string is longer than 
8 characters, the string is padded with blanks on the right. 



Predefined Functions 



Type Functions 
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Standard Pascal offers two predefined functions, ord and chr, that convert 
predefined scalar types. 
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Min 



Max 



Lbound 



Hbound 



Pascal allows all scalar types to have a conversion function that converts an in- 
teger into that scalar type. As in standard Pascal, the ord function converts from 
the scalar type to integer. Pascal lets all type identifiers for a scalar type be 
used in an expression to convert its integer argument into the corresponding sca- 
lar value. Thus, if color is an enumerated data type, color(i) is a function that 
returns the i+l-th element of the enumeration (i.e., color (0 ) is first, 
color (1) is second, etc.). 

boolean-var := boolean (integer-expr) 
char-var := char (integer-expr) 
color-var := color {integer-expr) 

In Pascal, the ord function also operates on pointers, returning the machine ad- 
dress of the item referenced by the pointer. A data type identifier that repre- 
sents a pointer data type can also be used to convert a cardinal number into a 
valid pointer of that type. This feature is highly machine dependent and should 
be used sparingly. 



scalar-var : = min (scalar-^xpr [, scalar-expr] . . . ) 

The min function returns the smallest of its scalar arguments. For example: 

min (-6, 3, 5) 

returns -6. 

scalar-var :~ max (scalar-expr [, scalar-expr] . . . ) 

The max function returns the largest of its scalar arguments. For example: 
max (-2, 3, 5) 

returns 5. 

scalar-var :- lbound (array-type [, index] ) 

The lbound function returns the lower bound of the array type specified by the 
first argument. The array type must be specified by a type identifier or a vari- 
able whose type is an array. If the array is multi-dimensioned, then an optional 
second argument specifies the dimension; 1, specifying the first or outermost 
dimension, is the default. 

scalar-var := hbound (array-type [, index] ) 

The hbound function returns the high bound of the array type specified by the 
first argument. The array type must be specified by a type identifier or a vari- 
able whose type is an array. If the array is multi-dimensioned, then an optional 
second argument specifies the dimension; 1 is the default which means the first 
(outermost) dimension. 
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First 



Last 



Argc 



Clock 



Bitand 



Bitor 



Bitxor 



Bitnot 
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scalar-var :- first {type-identifier) 

The first function returns the first (lowest) value of the named scalar type. For 
example, first(integer) returns -2147483848. 



scalar-var := last (type-identifier) 

The last function returns the last (highest) value of the named scalar type. For 
example, last(integer) returns 2147483847 (maxint). 

Sizeof 

sizeof (type-id [, tag field-value] . . . ) 

The sizeof function returns the number of bytes occupied by the data type speci- 
fied as an argument. If the argument specifies a record with a variant record 
part, then additional arguments specify the value of each tagfield. 

integer-var := argc 

The argc function returns the number of arguments passed to the program. The 
value of the function is 1 or greater. 

integer-var :== clock 

The clock function returns the milliseconds of processor time used by the cur- 
rent process. 

integer-var := bitand (in teger-expr, integer-expr) 

The bitand function returns the bit-wise and of the two integer valued oper- 
ands. 

integer-var := bitor (in teger-expr, integer-expr) 
The bitor function returns the bit-wise or of the two integer valued operands, 

integer-var := bitxor (integer-expr, integer-expr) 

The bitxor function returns the bit-wise exclusive or of the two integer valued 
operands, 

integer-var := bitnot (integer-expr) 
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The bitnot function returns the bit-wise not of the integer valued operand. 



Lshift 



Rshift 



integer-var := lshift (in teger-expr, integer-expr) 

The lshift function returns the left shift of the first integer valued operand by 
the amount specified in the second argument. Zero bits are inserted on the 
right. 



integer-var :- rshift (integer-expr, integer-expr) 

The rshift function returns the right shift of the first integer valued operand by 
the amount specified in the second argument. Sign bits are inserted on the left 
if the operand is an integer type; zero bits are inserted if the operand is a cardi- 
nal type. You can force zero bits with the following construct: 

rshift (cardinal (intexpr) , shift amount) 



I/O Extensions 



Specifying Radix in the Write Statement 



Pascal permits the specification of operands in a write statement that write inte- 
ger or cardinal numbers in any radix from 2 through 36. The following code 
writes a number in each radix: 

for i:= 2 to 36 do 
writeln (' x is r , x : 1 : i, ' in radix ' , i; 1) ; 

A minus sign precedes any printed number if the type of the number is integer 
and the value is less than zero. If the type of the number is cardinal, then the 
compiler interprets the number as not having a sign and prints the sign bit as 
part of the number rather than with a negative sign. 



Filename on Rewrite and Reset 



Pascal accepts an optional string argument that specifies the path name of the 
file to be opened/created. Otherwise, it creates a file in a temporary area. 

reset (input [ f string]) 
rewrite (output [ , string]) 

Reading Character Strings 

Pascal allows you to read characters into a string array, while standard Pascal 
does not. A string is defined to be a packed array of char whose lower bound is 
1 and whose upper bound is greater than 1. The array is padded with blanks 
when it is longer than the line, and the line is truncated if it is longer than the 

Languages Programmer's Guide B-1 3 



Appendix B 



array. In the following example, characters are read into the array one line at a 
time until the end-of-line (eoln) is reached. 



program Count Lines (input, output) ; 
type 

string80 = packed, array [1 •, 80] of char; 
var 

Line : string80; 
begin 



while not eo£ (input) do begin 
readln( input , Line) 



i := i+1; 
end; {while} 
write ('The number of lines is ' , 1:1); 



( 



Reading and Writing Enumeration Types 



Pascal provides an extension to permit any enumerated scalar type to be speci- 
fied as the operand of a READ or a WRITE to a text file. 

Reading an enumeration value interprets the programmer-defined name, pre- 
ceded optionally by blank, tab, or new-line characters. The end of the name is 
delimited by any character that is not a valid character of an identifier. The de- 
limiting character is skipped. Good choices for delimiting characters are blanks, 
tabs, commas, or new-lines. 

Writing an enumerated value causes the programmer defined name to be written 
out to the text file. (Input and output is case sensitive.) 

The following is an example of using enumerated values. 



c 



program testenum( input , output) ; 
type 

color = (red, orange, yellow, green, blue, violet, 

black, white) ; 
var 

vcolor : color; 
begin 

repeat 

writeln ('enter color'); 
read (vcolor) ; 

writeln ('The color is ', vcolor : 0); 
until eof; 
end. 



( 
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If any color other than one specified in the color enumeration is entered, the 
following message appears: 

enumerated value string not within type 
The color is red 

where string represents the incorrect value entered. When an incorrect value is 
entered, the first value in the enumeration (red in the above example) is written 
to the screen. 



Lazy I/O 



Pascal provides an interpretation of the standard that simplifies terminal-ori- 
ented I/O. Standard Pascal defines the file pointer of a text file to point to the 
first character of a line after a reset or readln operation. This makes it difficult 
to issue a prompt message because the physical I/O operation for the next line 
occurs at the end of the readln procedure. 

Pascal follows standard Pascal conventions, except that it doesn't perform 
physical I/O until the user actually uses the file pointer. In effect, it's lazy about 
performing the I/O operation. This allows the user to issue a prompt message 
after the readln (or reset) prior to the time when the user's terminal attempts to 
read the next line. 



Standard Error 



Pascal provides an additional predefined text file called err which is mapped to 
UNIX standard error. Also, the files input and output are mapped to the UNIX 
file standard input and standard output. 

Predefined Data Type Extensions 

Double 

Pascal accepts a new predefined data type called double that represents a dou- 
ble precision floating point number. If either operand of an expression is dou- 
ble, then the compiler uses double precision. 



Cardinal 



Pointer 



Pascal accepts the cardinal data type that represents an unsigned integer in the 
range 0.. 4294967295 (2**32-1). If either operand of an expression is cardinal, 
then the compiler uses unsigned arithmetic. 

Pascal defines a new predefined data type called pointer that is compatible with 
any pointer type. This type can be thought of as the type of the Pascal value 
nil. Use pointer to write procedures and functions that accept an arbitrary 
pointer type as an operand. You cannot directly dereference a variable of this 
type because it is not bound to a base type. To dereference it, you must first 
assign the variable to a normally typed pointer. 

Compiler Notes 
Macro Preprocessor 

Pascal invokes the C preprocessor (cpp) before each compilation allowing, you 
to use cpp syntax in the program. The cpp variables LANGUAGE_PASCAL, 
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LANGUAGE^, LANGUAGE JFORTRAN, and LANGUAGE^ASSEMBLY 

are defined automatically, allowing you to build header files that can be used by 
different languages. The following example shows two conditional statements, 
one written in Pascal and the other in C. 



( 



#ifdef LANGUAGEJPASCAL 
type 

pair — 
record 

high, low : integer; 
end {record}; 
#end 

#ifdef LANGUAGE_C 
typedef struct { 
int high f low; 
} pair; 
#end 



Short Circuiting 



You can also use the full conditional expression syntax of cpp, as well as C 
style comments (/* ... */), which are stripped during compilation. 

Pascal always short circuits boolean expressions. Short circuiting is a technique 
where only a portion of a boolean expression is actually executed. For example, 
in 

if (P <> nil) and (P A . Count > 0) then 

the expression involving P A .Count isn't evaluated if the first expression is false. 
This extension is permitted by the Pascal standard; a program that relies on this 
feature, as does this example, would not be portable. 



Translation Limits 



The following table shows the maximum limits imposed on certain items by the 
Pascal compiler. 



Pascal Specification 


Maximum 


Literal string length 
Procedure nesting levels 
Set size 
Significant characters 


288 

20 

481 -512* 

32 


* Depends on actual limits of data item. 



( 
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What Is Byte Ordering? 



A machine's byte ordering scheme (or whether a machine is big-endian or lit- 
tle-endian) affects memory organization and defines the relationship between 
address and byte position of data in memory. MIPS machines can be big-en- 
dian or little-endian. 



Big-Endian Byte Ordering 



Big-endian machines number the bytes of a word from to 3. Byte holds the 
sign and most significant bits. For halfwords, big-endian machines number the 
bytes from to 1. Again, byte holds the sign and most significant bits. Ma- 
chines that use big-endian schemes include the IBM s/370 and Motorola 
MC68000. 
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Figure CJ. Big-endian byte ordering. 
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Little-Endian Byte Ordering 



Little-endian machines number the bytes of a word from 3 to 0, Byte 3 holds 
the sign and most significant bits, For halfwords, little-endian machines num- 
ber the bytes from 1 to 0. Byte 1 holds the sign and most significant bits. Ma- 
chines that use little-endian schemes include; DEC VAX & 11/780, Intel 
80286, and National Semiconductor 32000. 
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? command, in DBX, 5-34 
/ command, in DBX, 5-34 

Numbers 

-5, compiler option, 1-8 



-A link editor option, 1-16 

a.out default, for -o option, 1-9 

activation levels, 5-3 

alert character, in Pascal, B-3 

alias command, in DBX, 5-22 

ar command, syntax, 1-33 

archiver 
ar command, 1-32 

examples, 1-33 

options, 1-34—1-37 
purpose, 1-32 

argc, Pascal predefined function, B-12 

argv, Pascal predefined procedure, B-10 

as driver command, 1-2 

assembler, driver command, 1-2 

assert, Pascal predefined procedure, B-10 

assign command, in DBX, 5-40 

auto (C storage class), 2-6 

B 

-B link editor option, 1-16 
-B num link editor option, 1-16 
BREAK statement, in Pascal, B-6 
BSD memory map, producing, 1-18 
-Bstring link editor option, 1-16 
-b link editor option, 1-16 
backslash character, in Pascal, B-3 



backspace character, in Pascal, B-3 

basic block counting, overview, 4-2 

-bestGnum option 
and -G option, 1-9 
description, 1-17 
examples, 4-32 

big endian. See byte ordering 

bitand, Pascal predefined function, B-12 

bitnot, Pascal predefined function, B-12 

bitor, Pascal predefined function, B-12 

bitxor, Pascal predefined function, B-12 

boolean expressions, short circuiting,, in Pascal, B-16 

byte ordering, C-l 

-EB (big endian) option, 1-10 

-EL (little endian) option, 1-10 

for C language structures, 2-2 

Pascal arrays and records, 2-11—2-17 



C language 
arrays, 2-2 
data types, 2-1—2-6 
driver command, 1-2 
extensions, A-3 

interface to Pascal programs, 3-1—3-10 
operators used by DBX, 5-10 
storage classes, 2-6 — 2-7 
structures, 2-2 
translation limits, A-3 
unions, 2-6 
vararg.h macros, A-l 

C macro preprocessor, option, 1-8 

-C option 
for C and assembler, 1-8 
for Pascal and FORTRAN, 1-8 

CASE statement ranges, in Pascal, B-5 

CONTINUE statement, in Pascal, B-6 

Cobol, driver command, 1-2 

-c option 
See also -o option 
description, 1-8 

cache conflicts, eliminating, 4-33 

calls 
C programs from Pascal, 3-7 — 3-10 
Pascal programs from C, 3-4 — 3-7 
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cardinal, Pascal predefined data type, B-15 

carriage return character, in Pascal, B-3 

catch command, in DBX, 5-45 

cc driver command, 1-2 

characters, maximum significant, in Pascal, B-16 

chr, Pascal predefined function, B-10 

clock, Pascal predefined function, B-12 

cobol driver command, 1-2 

common files, 1-12 

compiler options 
byte-ordering, 1-10 
compiler development, 1-12 
debugging, 1-11, 5-5 
general, 1-7 
optimizer, 1-12 

compiling multi-language programs, 1-6 

constant expressions, in Pascal, B-3 

cont command, in DBX, 5-39 

conti command, in DBX, 5-53 

-cord 
compiler option 

description, 1-8 

example, 4-33—4-34 
prof option, example, 4-33—4-34 
reducing cache conflicts with, 4-33 

-count link editor option, 1-17 

-countall link editor option, 1-17 

cpp (C preprocessor), invoked by Pascal, B-15 

-cpp option, 1-8 



date, Pascal predefined procedure, B-10 

DBX 
command file, 5-5 
command summary, 5-57 
command syntax, 5-7 
commands, 5-12 
constants, 5-10 
data types, 5-10 
examining program state, 5-46 
example, 5-7 
expressions, 5-9 
guidelines to using, 5-3 
how to use, 5-5— 5-8 
invocation syntax, 5-6 
machine level debugging, 5-51 
purpose, 5-2 
quitting, 5-7 
sample program, 5-64 
setting breakpoints, 5-41 
variables, predefined, 5-18—5-19 

debugging 
SeealsoDBX 
before optimization, 5-5 
-g options, 1-11 
guidelines, 5-3 
how to use DBX, 5-5—5-8 
output, 5-4 

declarations, in Pascal, B-6 

delete command, in DBX, 5-30 

double, Pascal predefined data type, B-15 

down command, in DBX, 5-47 

driver, 1-1 
commands, 1-2 

dump command, in DBX, 5-50 
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D 

-D num link editor option, 1-16 

-D option, 1-8 

data types 
C language 

alignment, 2-1 — -2-6 

size, 2-1 — 2-6 

value ranges, 2-1 — 2-6 
Pascal 

alignment, 2-8—2-17 

size, 2-8 

value ranges, 2-8 — 2-17 



-E option, 1-8 

-EB link editor option, 1-16 

-EL link editor option, 1-16 

-e epsym link editor option, 1-16 

edit command, in DBX, 5-34 

endian byte ordering. See byte ordering 

escape characters, B-3 

examples 
-cord option, using to reduce cache conflicts, 4-33 
-k option, 4-22—4-24 
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ar (archiver) command, 1-33 
-bestGnum option, 4-32—4-33 
Ccall 

to Pascal function, 3-6 

to Pascal procedure, 3-6 
C main routine, 3-4 
C routine passing strings to Pascal, 3-7 
compiling multi-language programs, 1-6 
excluding libraries, 4-32 — 4-33 
file command listing, 1-31 
-j option, 4-22— 4-24 
link editor -1 option, 1-14 
linking objects, 1-6 
nm symbol table listing, 1-27 
-nocount option, 4-32 — 4-33 
-03 optimization, 4-20—4-21 
odump listings, 1-23 — 1-27 
optimizing with ulink, umerge, 4-20 — 4-21 
Pascal call 

passing arrays to C function, 3-10 

to C function, 3-9 

to C procedure, 3-9 

to C routine, 3-3 
Pascal main routine, 3-4 
pixie, using to reduce cache conflicts, 4-33 
prof, using to reduce cache conflicts, 4-33 
size command listing, 1-31 
ucode object library 

building, 4-24 

using, 4-24 

extern (C storage class), 2-6 
external directives, in Pascal, B-7 



file command, 1-31 
in DBX, 5-32 

file suffixes, 1-3 

first, Pascal predefined function, B-12 

form feed character, in Pascal, B-3 

formal directives, in Pascal, B-7 

func command, in DBX, 5-31 



-G num link editor option, 1-17 

-G option, 1-9 
See also global data area 

-g debugging options, 1-1 1 

global data area 
controlling size of, 4—31 
determining optimal size, 4-32 
layout, 4-31 
purpose, 4-31 

goto command, in DBX, 5-39 

H 

hbound, Pascal predefined function, B-ll 
header files, 1-12 

hexadecimal value character, in Pascal, B-3 
horizontal tab character, in Pascal, B-3 



-F link editor option, 1-17 

FORTRAN, operators used by DBX, 5-10 

FORTRAN, driver command, 1-2 

-f fill link editor option, 1-16 

f77 driver command, 1-2 

-feedback 
compiler option 

description, 1-8 

example, 4-33—4-36 
prof option 

description, 4-16 

example, 4-33—4-36 



I 

-I dimame option, 1-9 

-I option, 1-9 

-i option, 1-9 

ignore command, in DBX > 5-45 

including files, 1-12, 1-13 

invocation counting, overview, 4-2 



-j option 
description, 1-9 
examples using, 4-22—4-24 
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with -i option, 1-9 
-jmopt linkeditor option, description, 1-17 
-jmpopt link editor option, purpose, 4-34 
jump delay slot, and link editor, 4-34 

K 

-k option, 1-9 
examples using, 4-22 — 4-24 

-ko option, 1-9 



-L dirname link editor option, 1—18 

-L link editor option 
and L dirname option, 1-18 
description, 1-18 

language interfaces, 3-1 

languages supported, 1-2 

last, Pascal predefined function, B-12 

lazy I/O, in Pascal, B-15 

lbound, Pascal predefined function, B-l 1 

Id command, 1-14 

/lib link library, specifying, 1-18 

libraries, specifying, 1-14 

link editor 
how to run, 1-14 
purpose, 1-14 
version number, determining with -V option, 1-19 

link library, specifying, 1-18 

list command, in DBX, 5-33 

literal string, maximum length, in Pascal, B-16 

little endian. See byte ordering 

lshift, Pascal predefined function, B-13 

-Ix link editor option, 1-18 

M 

-M link editor option, 1-18 
-m link editor option, 1-18 
max, Pascal predefined function, B-l 1 



memory map, producing 
BSD format, H8 
System V format, 1-18 

min, Pascal predefined function, B-ll 

N 

-N link editor option, 1-18 

NMAGIC file, creating, 1-18 

-n link editor option, 1—18 

newline character, in Pascal, B-3 

next command, in DBX, 5-37 

nexti command, in DBX, 5-53 

nm list utility, 1-27 

-nocount link editor option, 1-17 

-nocpp option, 1-9 
See also -cpp option 

-nojmpopt link editor option 
description, 1-17 
purpose, 4-34 

o 

"O optimizing options, 4-19—4-20 

-03 optimizer option, example, 4-20 

OMAGICfile, creating, 1-18 

OTHERWISE clause, in Pascal, B-5 

-o filename link editor option, 1-19 

-o filename option, 1-9 

object file (a.o) 
producing with -c option, 1-8 
tools, 1-20— 1-38 

octal value character, in Pascal, B-3 

odump (object file utility) 
example output, 1-23 
options, 1-21 
purpose, 1-20 
syntax, 1-20 

-Olimit option 
purpose, 4-21 
using to improve performance, 4-21 

optimization 
-O options, 1-12 
benefits, 4-17 
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debugging before, 4-17 

effect of -C bounds checking options, 4-17 

full, examples, 4-20—4-21 

global, 4-16 

improving 

C and FORTRAN programs, 4-29 

C and Pascal programs, 4-25-— 4-28 

C programs, 4-29 

C, Pascal, and FORTRAN programs, 4-24, 4-30 

Pascal programs, 4-30 
loops, 4-17 

-O options, 4-19—4-21 
of frequently used modules, 4-22-^4-24 
of separate compilation units, 4-18 — 4-19 
register allocation, 4-18 

options 
compilation, 1-8 — 1-12 
link editor, 1-15—1-20 

ord, Pascal predefined function, B-10 



-P option, 1-9 

Pascal 
arrays, 2-11 

arrays and records, byte ordering, 2-1 h 
data types, 2-8—2-17 
driver command, 1-2 
interface to C programs, 3-1—3-10 
operators used by DBX, 5-10 
records, 2-12 
variant records, 2-15 

-p,-pl option, 1-10, 4-26 
See also profiling 

Pascal language, B-l 
extensions, B-5 
I/O extensions, B-13 
constants, B-2 
predefined functions, B-10 
predefined procedures, B-10 

pc driver command, 1-2 

pc-sampling 
how to, 4-12 
overview, 4-2 

performance, improving 
coding hints, 4-24 — 4-30 
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limiting size of global data area, 4-31- 
reducing cache conflicts, 4-33 
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striping symbol table info with -s option, 1-19 

See also -x option 
using the optimizer (-0) options, 4-16 
using the profiler (prof), 4-1 — 4-13 

-pfile link editor option, description, 1-19 

-pixie, prof option, description, 4-14 

pixie 
overview, 4-2 

reducing cache conflicts with, 4-33 
using to profile, 4-8 

pixie program, example, 4-33 — 4-34 

PL/I, driver command, 1-2 

pll driver command, 1-2 

playback command, in DBX 
for input, 5-27—5-28 
for output, 5-28 

pointer, Pascal predefined data type, B-l 5 

print command, in DBX, 5-48 

printf command, in DBX, 5-48 

printregs command, in DBX, 5-49 

procedures nesting levels, maximum, in Pascal, B-16 

prof. See profiling 

profiling, 4-10 
basic block counts, how to, 4-8 — 4-10 
examples, output listings, 4-3 — 4-8 
file names, 4-13 
overview, 4-1 

pc-sampling, how to, 4-12 — 4-13 
prof command 

format, 4-13—4-14 

options, 4-14 — 4-16 
reducing cache conflicts with, 4-33 

Q 

qualifying variable names (dbx), 5-9 
quotation mark character, in Pascal, B-3 



READ, in Pascal, B-14 
RESET I/O extensions, in Pascal, B-13 
RETURN statement, in Pascal, B-5 
REWRITE I/O extensions, in Pascal, B-13 
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-r link editor option, 1-19 

record command, in DBX 
for input, 5-25—5-26 
for output, 5-26—5-27 

register (C storage class), 2-6 

rerun command, in DBX, 5-36 

return command, in DBX, 5-38 

rshift, Pascal predefined function, B-13 

run command, in DBX, 5-36 



-S, link editor option, 1-19 

-S option. See -c option 

System V memory map, producing, 1-18 

.s file, producing with -S option, 1-10, 4-26 

-s link editor option, 1-19 
See also -x option 

set, DBX command, 5-16 

set size, maximum, in Pascal, B-16 

set sizes, 2-17 

sh command, in DBX, 5-29 

shared variables, in Pascal, B-8 

single quote character, in Pascal, B-3 

size command, 1-31 

source command, in DBX, 5-27 

source level debugger, 5-2 

source-level debugger. See DBX 

special character, Pascal, B-3 

static (C storage class), 2-6 

status command, in DBX, 5-29 

-std option, 1-10, 4-26 

step command, in DBX, 5-37 

stepi command, in DBX, 5-53 

stop at command, in DBX, 5-41 

stop if command, in DBX, 5-43 

stop in command, in DBX, 5-42 

stopi command, in DBX, 5-52 

storage classes (C language), 2-6—2-7 



string array characters, reading, in Pascal, B-13 

symbol table 
dumping, 1-27 

stripping from object modules, with -x option, 1-19 
See also -s option 



-T num link editor option, 1-19 

text segment, setting origin with -T num option, 1-19 

time, Pascal predefined procedure, B-10 

trace command, in DBX, 5-43 

tracei command, in DBX, 5-54 

type functions, Pascal, B-10 

U 

-U option, 1-10, 4-26 

-u symname link editor option, 1-19 

ucode object library, building, 4-24 

ulink, umerge 
examples, 4-20— 4-21 
invoking for optimization, 4-19 

unalias command, in DBX, 5-22 

unset, DBX command, 5-17 

up command, in DBX, 5-47 

use command, in DBX, 5-31 

/usr/lib link library, specifying, 1-18 

/usr/local/lib link library, specifying, 1-18 



-V 
compiler option, 1-10, 4-26 
link editor option, 1—19 

-VS num link editor option, 1-19 

-v 
compiler option, 1-10, 4-26 
link editor option, 1-19 

vararg.h macros, A-l 

variable number of arguments, A-l 

vertical feed character, in Pascal, B-3 



c 



c 



( 
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volatile (C storage class), 2-6 



which command, in DBX, 5-35 



W 

WRITE I/O extensions, in Pascal, B-14 
WRITE I/O extensions, in Pascal, B-13 
-w option, 1-10, 4-26 
whatis command, in DBX, 5-35 
when command, in DBX, 5-44 
where command, in DBX, 5-46 
whereis command, in DBX, 5-35 



~x link editor option, 1-19 



ZMAGIC files, creating, 1-17 
-z link editor option, 1-17 
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Customer Response Card 

Your comments, which can assist us in improving our products and our 
publications, are welcome. 

If you wish to reply, be sure to include your name and address, and the name 
and part number that appears on the first page of this manual. 

Thank you for your cooperation. 

No postage necessary if mailed in the U. S. A. 

After writing comments, detach this page and then fold, seal, and mail. 
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MIPS may use and distribute any of the information you supply in any way it 
believes appropriate without incurring any obligation whatever. You may, of 
course, continue to use the information you supply. 
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